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Abstract 


IBM PC DOS 7 has been designed for all types of users who need an efficient 
single tasking personal computer operating system. It incorporates many 
new utilities such as anti-virus software, comprehensive backup programs, 
PCMCIA support and DOS Pen extensions. Also incorporated are new 
features to enhance the available memory and disk space. 

This book is a technical reference, upgraded from IBM DOS 5.02 and written 
for DOS programmers, who develop applications for IBM Personal 
Computers or compatible systems. 

The program developer should be competent on the IBM Personal Computer 
and/or the Personal System/2 and should be familiar with DOS and at least 
one personal computer programming language. 

(381 pages) 
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Preface 


This book is written for programmers whe deveiop appiicatiens for iBM 
Personai Computers and PC DOS 7. 

The program deveioper shouid be competent on the iBM Personai Computer 
and/or the Personai System/2 and shouid be famiiiar with DOS and at ieast 
one personai computer programming ianguage. 


How This Document is Organized 

The document is organized as foiiows: 

• Chapter 1, “introduction” provides detaiis of the beok and its usage. 

• Chapter 2, “Accessing Disks” provides the necessary information and 
system architecture to access disks. 

• Chapter 3, “Accessing Fiies with Fiie Flandies” gives information on 
reading, writing and managing fiies using fiie handies. 

• Chapter 4, “Accessing Fiies Using Fiie Controi Biocks” gives information 
on reading, writing and managing fiies using fiie controi biocks. 

• Chapter 5, “Managing Device i/0” provides information on handiing 
device input and eutput operations, for dispiays, keyboard and other 
devices. 

• Chapter 6, “Controiiing Processes” detaiis the methods used to manage 
memery and controi programs. 

• Chapter 7, “Debugging a Program” describes the DEBUG utiiity pregram. 

• Chapter 8, “Writing an Instaiiabie Device Driver” describes the 
information needed to write device drivers. 

• Appendix A, “PC DOS 7 interrupts” provides information to support the 
use ef the PC DOS 7 interrupts. 

• Appendix B, “PC DOS 7 Functien Caiis” detaiis the iNT 21 FI DOS function 
calls. 

• Appendix C, “I/O Control for Devices (lOCtI)” describes hew to set or get 
device informatien associated with open device handles. 

• Appendix D, “Expanded Memory Support” shows the LIM functions 
supported by PC DOS 7. 

• Appendix E, “DOS Protected Mode Services” describes the supported 
functions supported by PC DOS 7 DPMS driver. 
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• Appendix F, “Task-swapping” detaiis the functions found within the 
user-sheil. 

• Appendix G, “PC DOS 7 Viewer” overviews the creation of oniine 
viewabie documents. 

• Appendix H, “Misceiianeous Controi Biocks” show some additional 
control blocks. 


Related Publications 

The publications listed in this section are considered particularly suitable for 
a more detailed discussion of the topics covered in this document. 

• PC DOS 7 Command Reference and Error Messages, S83G-9309-00 

• PC DOS 7 Keyboard and Codepage Reference, S83G-9310-00 

• PC DOS 7 REXX User's Guide and Reference, S83g-9228-01 

• CID Enablement of DOS Local Area Networks, SC31-6833 

• OS/2 Warp IPF Programming Guide, G25H-71 10-00 

• Everyday DOS, ISBN 1-56529-363-0 


International Technical Support Organization Publications 

A complete list of International Technical Support Organization publications 
with a brief description of each may be found in: 

Bibliography of International Technical Support Organization Technical 
Bulletins, GG24-3070. 

To get listings of ITSO technical bulletins (redbooks) online, VNET users may 
type: 

TOOLS SENDTO WTSCPOK TOOLS REDBOOKS GET REDBOOKS CATALOG 
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— How to Order ITSO Technical Bulletins (Redbooks) 

IBM employees in the USA may order ITSO books and CD-ROMs using 
PUBORDER. Customers in the USA may order by cailing 1-800-879-2755 
or by faxing 1-800-284-4721. Visa and Master Cards are accepted. 
Outside the USA customers shouid contact their IBM branch office. 

Customers may order hardcopy redbooks individuaiiy or in customized 
sets, cailed GBOFs, which reiate to specific functions of interest. IBM 
employees and customers may also order redbooks in online format on 
CD-ROM collections, which contain the redbooks for multiple products. 
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Chapter 1. Introduction 


This chapter provides information about this book, inciuding the foiiowing: 

• Organization of the book for quick information retrievai 

• New and enhanced PC DOS 7 services 

• Minimum hardware configuration. 

This book is organized by iogicai appiication program deveiopment stages 
necessary to deveiop an appiication program on PC DOS 7. 

in addition, the book teiis how to make best use of the operating system by 
writing your own device driver or by using the system extensions. 

Each chapter describes a particuiar subject. You do not need to read the 
entire book to create programs or soive probiems. Key topics aiso can be 
found by referring to the index and the tabie of contents. 

The appendixes contain reference information for quick retrievai. They 
contain the entire numericai iist of PC DOS 7 services, inciuding interrupts, 
function caiis and device driver services. 


What's New for PC DOS 7 

PC DOS 7 inciudes the foiiowing new features as well as enhancements to 
features in prior versions of PC DOS: 

• The PC DOS Setup program includes enhancements that allow you to: 

- Use a mouse device during installation. 

- Use the DOSKey program immediately after installing DOS, because 
the DOSKEY command-line statement is now automatically added to 
your AUTOEXEC.BAT file. 

- View or edit the changes Setup made to your CONFIG.SYS and 
AUTOEXEC.BAT files prior to system restart. For example, if you use 
another command retrieval program other than DOSKEY, you can 
edit the AUTOEXEC.BAT file and delete this command-line statement 
before the Setup changes become effective. 

- Understand what changes were made to these system files by 
reviewing comment lines added by Setup. Comment lines describe 
what was added in these files or what was replaced, updated, or 
deleted if upgrading your version of DOS. 
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See the installation information for a complete list of Setup 
enhancements. 


• RAMBoost more effectively handles multiple configurations now. The 
most common questions asked about RAMBoost and RAMBoost Setup 
are now included in a tips and techniques section. 

• The E Editor has the following enhancements for PC DOS 7: menu 
selection, mouse awareness, expanded sort capabilities, deleted record 
recovery, ability to change E Editor default settings (for color, tab and 
margin settings, window mode, and a new browse mode for the online F1 
help. 

• A new program. File Update, watches the files on up to two different two 
computers to help keep files synchronized (for example, when you work 
on one computer at home and one at work). 

• A new documentation viewer, PC DOS Viewer, is used to read or search 
online books for PC DOS information. Three online books are included 
with PC DOS: a Command Reference, a REXX Reference, and Error 
Messages, which includes the more common error messages. 

This viewer also allows quick access to help for DOS commands, DOS 
device drivers, and DOS .INI files information. In addition you can get 
quick help for REXX commands or DOS error messages. 

• The enhanced Advanced Power Management driver (POWER.EXE) has 
added power management events. 

• Support is provided for certain docking device drivers. After typing either 
the DOSDOCK command for DOS or the DDPOPUP command for 
Windows, these drivers are dynamically loaded when PC DOS senses the 
appropriate docking devices. 

• The amount of conventional memory required by PC DOS has been 
reduced, allowing more memory for your applications. 

• The OCONFIG command now identifies and displays additional machines, 
adapters and planars. 

• The BACKUP command, formally included in DOS versions prior to PC 
DOS 6, has been returned as a command provided with PC DOS 7. 


New, Changed or Removed PC DOS Commands and Device Drivers 

The following commands and device drivers are new for PC DOS 7: 


ACALC 

BROWSE 

CHECK 

CNFIGNAM 


DPMS.EXE 

DYNALOAD 

FILEUP 

HCONVERT 


REMOVDRV 

REPORT 

RESIZE 

REXX 


STACHIGH.SYS 

STACKER 

STACWIN 

SYSINFO 
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CONFIG 

CRC 

CREATE 

□CONVERT 

□□POPUP 

□OSOATA 

□OSOOCK 


PASSWO 

PCM 

PCMCINST 

PCMFCISK 

PCMRMAN 

PCMSETUP 

PCMWIN 


SCREATE.SYS 

SCEFRAG 

SCIR 

SETUP (Stacker) 
SGROUP 
SSETUP 
STAC 


TUNER 

UNCOMP 

UNPACK2 

VIEW 

XCF 

XCFCOPY 


The following commands and device drivers are enhanced fcr PC DOS 7: 


ANSI. SYS 
BUFFERS 
□EFRAG 

□ ISKCOPY 

□ ISPLAY.SYS 


□OSKEY 
E (E Editor) 
EMM386.EXE 
FINU 
HELP 


HIMEM.SYS 

INTERLNK 

MSCUEX 

POWER 

QCONFIG 


RAMBOOST 

RAMBOOST.EXE 

RAMURIVE.SYS 

RAMSETUP 

SETUP 

SMARTURV.EXE 


For further information about new or enhanced DOS commands and device 
drivers, type heip foiiowed by the name of the command or device driver. 
Note: You must add the extensicn of the device driver fiie. For exampie, you 
wouid type FIELP ANSI. SYS to get online heip abcut the ANSI. SYS device 
driver. 


The foilowing commands and device drivers are no ionger provided with PC 
DOS 7: 

• SuperStor/DS compressicn commands repiaced by Stacker ccmmands. 

• PCMCIA Support commands replaced because of the new DOS and 
Windows fuil-screen instailation interfaces. 

• Commands no ionger provided by PC DOS. 

• Infrequentiy used ccmmands that are not being provided as part of PC 
DOS 7: 

- If you have a previcus version of DOS instaiied and are upgrading 
your system, these commands wiii not be remcved during 
instaiiation. 

- If you still want to use these commands and have no diskettes from 
previous versions of DOS, these commands wiii be prcvided through 
eiectronic deiivery, such as bulietin board services. 

If you have a licensed copy of PC DOS 6.3, you are authorized to 
copy these commands to any system with a iicensed copy PC DOS 7. 
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SuperStor/DS 
Commands No 
Longer Provided 


PCMCIA 
Commands No 
Longer Provided 


Removed 
Commands No 
Longer Provided 


Files Not Provided 


DBLSPACE.SYS 

MOUNT 

RTOOL 

SSTOR 

SSUNCOMP 

SSUTIL 

UDEOFF 

UDEON 

UNMOUNT 


PCMFDD.EXE 

PCMINFO 

PCMMTD 

PCMMTD.EXE 

WPCMINFO.CPL 


EXPAND 

MEUTOINI 

RECOVER 


4201. CPI 

4208. CPI 

COMP.COM 

EDLIN.EXE 

EPS.CPI 

EXE2BIN.EXE 

FASTOPEN.EXE 

GRAPHICS.COM 

GRAPHICS. PRO 

PPDS.CPI 

PRINTER. SYS 


New, Changed or Removed Optional Tools 

The new features of, and enhancements to, the optional tools provided with 
PC DOS 7 include: 

• REXX Language Support has been added as the PC DOS programming 
language tool of choice. REXX for DOS includes utilities and REXX 
commands that have been designed to work specifically with PC DOS. 

• Stacker Compression is now the optional tool that provides data 
compression for your system. Stacker Compression allows you to: 

- Convert any existing SuperStor/DS, DoubleSpace, or DriveSpace 
compression during Stacker Setup. 

- Convert any standalone version of Stacker Compression you might 
already have installed. 

- Make menu selections using either the Stacker DOS Toolbox or the 
Stacker Windows Toolbox. 

- Use data on compressed diskettes even on a computer that does not 
have Stacker installed. 

- Guard your data because every time you start up your system 
Stacker runs AutoProtect to make sure your data is in good condition. 

• PCMCIA Support now provides easier Setup procedures because of the 
new DOS and Windows full-screen interfaces included with PC DOS 7. 

The PCM. INI file is updated for you as you use the PCMCIA installation 
program to make selections for the type of PCMCIA support you want. 

• Central Point Backup has been enhanced. 

• Anti-virus protection provided with PC DOS (AntiVirus or IBM AntiVirus 
for Windows), has been updated to recognize and fix more viruses. If 
you are using IBM AntiVirus Services, a full-service, anti-virus protection 


4 PC DOS 7 



offering provided separateiy by iBM or if you have previousiy purchased 
the IBM AntiVirus/DOS product separateiy, you do not need to instali the 
IBM AntiVirus/DOS optional tool provided with PC DOS. For more 
information about IBM AntiVirus Services, refer to the coupon provided in 
the PC DOS 7 coupon bookiet. 

• IBM DOS Shell is now named the PC DOS Sheil. 


New, Changed or Removed .INI Files 

The foiiowing .INI files have been added, changed or are no longer required 
for PC DOS 7: 

New Changed Removed 

E.INI RAMBOOST.INI ADDSTOR.INI 

PCM. INI DBLSPACE.INI 

RAMSETUP.INI 
STACKER.INI 

New, Changed or Removed Keyboard Layouts and Code Pages 

The following keyboards and code pages have been added or changed for 
PC DOS 7: 

452 keyboard 

453 keyboard (provides the DIN 2137 German keyboard layout) 

865 code page 

912 code page 
915 code page 

The United Kingdom keyboard 168 has been removed. 

Type 
hel p keyb 

to see a tabie that summarizes ail the keyboard-layout and country 
code-page information. 


Minimum Hardware Configuration 

PC DOS 7 operates on ail IBM or IBM-compatible computers with at ieast 
512KB of conventionai memory. As a minimum, you must have a computer 
that has a 1 .44MB-capacity, 3.5-inch diskette drive or a 1 .2MB-capacity, 
5.25-inch diskette drive specified as drive A. Your hard drive shouid have a 
minimum of 6.0MB of free space to instaii only the DOS files and Central 
Point Backup** for DOS. 18.5MB of free space is needed if you want to instaii 
PC DOS pius aii the optionai toois. 
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Chapter 2. Accessing Disks 


This chapter provides the necessary guide and system architecture 
information to heip you successfuiiy compiete the foiiowing tasks: 

• Accessing the disk 

• Requesting drive and disk information 

• Reading and writing data to the disk. 


The Disk Format 

Aii disks and diskettes formatted by PC DOS 7 are created with a sector size 
of 512 bytes. PC DOS 7 is formatted on a diskette or on a designated 
partition of a hard disk in the foiiowing order: 


PC DOS 7 Component 

Size 

The boot record 

1 sector 

The first copy of the File Allocation Table (FAT) 

Variable 

The second copy of the FAT 

Variable 

The disk root directory 

Variable 

The data area 

Variable 


The Boot Record 

The PC DOS 7 FORMAT command creates the boot record. For diskettes, the 
boot record resides on track 0, sector 1, side 0. For hard disks, it resides at 
the starting sector of the partition. Accessing any media (diskette or hard 
disk) that does not have a vaiid boot record causes an error message. 
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The following diagram shows the iayout ef the DOS boot record, it is piaced 
on aii disks to provide an error message if the user trys to start the 
workstation with a non-system disk in drive A:, if the disk is a system disk 
the boot record points to the first address of the operating system. 


OOH 

3 bytes 

JUMP Instruction to Executable Code 

03H 

8 bytes 

Optional OEM Name and Version 

OBH 

2 bytes 

Bytes Per Sector 

ODH 

1 byte 

Sectors Per Allocation Unit 

OEH 

2 bytes 

Reserved Sectors (Starting at 0) 

10H 

1 byte 

Number of File Allocation Tables 

11H 

1 byte 

Number of Root Directory Entries 

13H 

2 bytes 

Total Number of Sectors (if size is larger than 
32MB, this value is 0 and the size is at offset 

20H) 

15H 

1 byte 

Media Descriptor 

16H 

2 byte 

Number of Sectors Per FAT 

18H 

2 bytes 

Sectors Per Track 

1AH 

2 bytes 

Number of Pleads 

1CH 

4 bytes 

Number of Flidden Sectors 

20H 

4 bytes 

Total Number of Sectors (See offset 13FI) 

24H 

2 bytes 

Physical Drive Number 

26H 

1 byte 

Extended Boot Record Signature (29FI) 

27H 

4 bytes 

Volume Serial Number 

2BH 

11 bytes 

Volume Label 

36H 

7 bytes 

File System Identifier (FAT12 ),(FAT16 ).... 


A boot record must be written on the first sector of aii hard disks. A partition 
tabie is found at the end of the boot record. The tabie is constructed of 16 
byte entires and containing information about the partitions start and end 
head, sector and cyiinder positions. Aiso in the partition tabie is an boot 
indicator which is used to determine if the partition is bootabie, in which 
case it is set to 80H. A system indicator byte is used to show the type of 
operating system that owns the partition. The foliewing diagram shows the 
partition tabie structure and offsets: 
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Offset from 
start of Disk 

I 

Offset 

Size 

Description 

I 

IBEH 

I 

OOH 

1 byte 

Boot Indicator 


OlH 

1 byte 

Beginning Head 


02H 

1 byte 

Beginning Sector 


03H 

1 byte 

Beginning Cylinder 


04H 

1 byte 

System Indicator 


OSH 

1 byte 

Ending Head 


06H 

1 byte 

Ending Sector 


07H 

1 byte 

Ending Cylinder 


OSH 

4 bytes 

Relative Starting Sector 


OCH 

4 bytes 

Number of Sectors 

ICEH 

I 

OOH 

1 byte 

Boot Indicator 


OlH 

1 byte 

Beginning Head 


02H 

1 byte 

Beginning Sector 


03H 

1 byte 

Beginning Cylinder 


04H 

1 byte 

System Indicator 


OSH 

1 byte 

Ending Head 


06H 

1 byte 

Ending Sector 


07H 

1 byte 

Ending Cylinder 


OSH 

4 bytes 

Relative Starting Sector 


OCH 

4 bytes 

Number of Sectors 

IDEM 

I 

OOH 

1 byte 

Boot Indicator 


OlH 

1 byte 

Beginning Head 


02H 

1 byte 

Beginning Sector 


03H 

1 byte 

Beginning Cylinder 


04H 

1 byte 

System Indicator 


OSH 

1 byte 

Ending Head 


06H 

1 byte 

Ending Sector 


07H 

1 byte 

Ending Cylinder 


OSH 

4 bytes 

Relative Starting Sector 


OCH 

4 bytes 

Number of Sectors 

lEEH 

I 

OOH 

1 byte 

Boot Indicator 


OlH 

1 byte 

Beginning Head 


02H 

1 byte 

Beginning Sector 


03H 

1 byte 

Beginning Cylinder 


04H 

1 byte 

System Indicator 


OSH 

1 byte 

Ending Head 


06H 

1 byte 

Ending Sector 


07H 

1 byte 

Ending Cylinder 


OSH 

4 bytes 

Relative Starting Sector 


OCH 

4 bytes 

Number of Sectors 

lEFH 

I 

I 

I 

2 bytes 

55AAH Signature 


Figure 1. Partition Table 

The Boot Indicator has a value of 80H if the particular partition is bootable or 
OOH if the partition is not bootable. 

The last entry in the partition table is the 55AAH signature and is used to 
identify a valid boot record. 
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The following table show some of the system Indicators that may be used: 


OOH 

Unknown or no partition defined 

01H 

DOS 12 bit FAT (under 16MB) 

04H 

DOS 16 bit FAT (less than 65,536 sectors) 

OSH 

Extended DOS partition 

06H 

DOS partition (over 32MB) 

07H 

OS/2 High Performance File System 


— Note 

This table Is by no means complete, as other manufactures use different 
Indicators. 


The File Allocation Table (FAT) 

The File Allocation Table (FAT) occupies the sectors immediately following 
the boot record. If the FAT Is larger than one sector, the sectors occupy 
consecutive sector numbers. 

The FAT keeps track of the physical location of all files on the disk. If the 
FAT cannot be read because of a disk error, the contents of the files cannot 
be located. For this reason, two copies of the FAT are written on the disk. 

PC DOS 7 uses the FAT to allocate disk space to a file, one cluster at a time. 
The FAT consists of a 12-bit entry (1.5 bytes) or a 16-bit entry (2 bytes) for 
each cluster on the disk. On a hard disk, the number of sectors for each 
cluster are determined by the size of the disk. PC DOS 7 determines 
whether to create a 12-bit or 16-bit FAT by calculating the number of 8-sector 
clusters that can occupy the space on the disk. If the number of clusters Is 
less than 4086, a 12-blt FAT is created. If It Is greater, a 16-blt FAT Is 
created. 

Using the follewing formula, you can determine the number of sectors on a 
disk: 

TS=SPT * H * C. 

TS = the tetal number of sectors on the disk. 

SPT = the number of sectors per track or per cylinder. 

H = the number of heads. 

C = the number ef cylinders. 


10 PC DOS 7 




The number of sectors on a 10MB IBM hard disk, for example, is 
20740 (17 * 4 * 305). 

The first two entries in the FAT are not used to map data. They indicate the 
size and format of the disk. The first byte of the FAT designates one of the 
following: 


Hex 

Value 

Meaning 

FF 

Doubie-sided, 8 sectors per track diskette 

FE 

Single-sided, 8 sectors per track diskette 

FD 

Doubie-sided, 9 sectors per track diskette 

FC 

Single-sided, 9 sectors per track diskette 

F9 

Double-sided, 15 sectors per track diskette (1.2 MB) 

F9 

Double-sided, 9 sectors per track diskette (720 KB) 

F9 

Double-sided, extended Data Format (1.88 MB) 

F8 

Hard disk 

FO 

1 .44MB or 2.88MB 


The second and third bytes of the FAT contain the value FFFI. The fourth 
byte, used by 16-bit FATs only, contains the value FFFI. 

The maximum size 16-bit FAT supported by PC DOS 7 for media greater than 
32KB is 64KB entries, or 128KB of space on the disk. This is an increase in 
size from the IBM PC DOS 3.30 limit of 16KB entries. 

The Disk Directory 

When the FORMAT command is issued, it builds the root directory for all 
disks. If the disk is formatted with the IS option, the PC DOS 7 system files 
(IBMBIO.COM, IBMDOS.COM, and COMMAND.COM) are added to the disk. 
The following eight formats are used for 5.25-inch diskettes and 3.5-inch 
diskettes: 


Sides 

Sectors/ 

Track 

FAT 

Size 

Sectors 

DiR 

Sectors 

DiR 

Entries 

Sectors/ 

Cluster 

1 (5.25) 

8 

1 

4 

64 

1 

2 (5.25) 

8 

1 

7 

112 

2 

1 (5.25) 

9 

2 

4 

64 

1 

2 (5.25) 

9 

2 

7 

112 

2 

2 (5.25) 

15 

7 

14 

224 

1 
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Sides 

Sectors/ 

Track 

FAT 

Size 

Sectors 

DiR 

Sectors 

DiR 

Entries 

Sectors/ 

Cluster 

2 (3.5) 

9 

3 

7 

112 

2 

2 (3.5) 

18 

9 

14 

224 

1 

2 (3.5) 

36 

9 

15 

240 

2 


The Data Area 

Data files and subdirectories are stored in the last and largest part of a disk. 
Space is allocated as it is needed, a cluster at a time. This allocation 
method permits the most efficient use of disk space. As clusters become 
available, space can be allocated for new files. 


Accessing the Disk 

Most interrupt 21 H functions can be used to access a disk. Five other 
functions can be used to perform disk-related activity. 


Activity 

Function 

Number 

Resetting the disk and fiushing the fiie butter 

ODH 

Selecting the detauit disk drive 

OEM 

Determine the current disk 

19H 

Determining the boot drive 

3305H 

Requesting the amount of tree space on the disk 

36H 


Requesting Drive and Disk Information 

Information on disks and drives can be requested by using the following INT 
21 H functions: 


Activity 







Function 

Number 

Requesting 

the 

current drive number 




19H 

Requesting 

disk 

allocation 

information 

about 

the 

detauit drive 

1 BH 

Requesting 

disk 

allocation 

information 

about 

the 

specified drive 

1CH 


12 PC DOS 7 






Reading and Writing Data Directiy to the Disk 

PC DOS 7 provides two interrupts, 25H and 26H, to read and write data to a 
disk. 



Interrupt 

Activity 

Number 

Reading from specified disk sectors 

25H 

Writing to specified disk sectors 

26H 
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Chapter 3. Accessing Files with File Handles 


The information necessary to compiete the foilowing tasks is provided in this 
chapter: 

• Reading and writing data to a fiie 

• Requesting and specifying fiie attributes 

• Accessing directories 

• Searching for fiies in directories 

• Requesting and specifying Nationai Language Support (NLS) 

• Controiiing Network Operations. 

PC DOS 7 provides nine functions within interrupt 21 H to create, open, ciose 
and deiete a fiie. 


Activity 

Function 

Number 

Creating a new file or replacing an old file 

3CH 

Opening a file 

3DH 

Closing a file handle 

3EH 

Deleting a file 

41 H 

Renaming a file 

56H 

Creating a new file with a unique name 

5AH 

Creating a new file 

5BH 

Locking and unlocking read/write access to regions of a file 

5CH 

Creating and opening a file with extended parameters 

6CH 


Filenames 

To name a fiie, the appiication program suppiies a pointer to an ASCIIZ 
string giving the name and iocation of the fiie. A fiiename contains an 
optionai drive ietter, path, or fiie specification terminated with a hexadecimai 
0 byte. Foiiowing is an exampie of a filename string: 

' B:\LEVELl\LEVEL2\FILEr, 0 

The maximum size of a filename is 64 bytes, including the path, name and 
null terminator. All function calls that accept path names accept a forward 
slash (/) or backslash (\) as path separator characters. 
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File Handles 

The open or create function calls return a 16-bit value called a file handle. 
To perform file I/O, a program uses the file handle to reference the file. 
Once a file is opened, the program no longer needs to maintain the ASCIIZ 
string pointing to the file. PC DOS 7 keeps track of the location of the file, 
regardless of which directory is current. 




Function 

Activity 


Number 

Specifying an additional file handle 

for a file 

45H 

Pointing the existing file handle to 

another file 

46H 

Specifying the number of open file 

handles 

67H 


The number of file handles that can be open at one time by all processes can 
be specified with the FILES command in CONFIG.SYS. There are 20 default 
handles available to a single process. All handles inherited by a process 
can be redirected. 

Each open handle is associated with a single file or device, but several 
handles can reference the same file or device. Thus, the maximum handle 
limit can exceed the number specified with the FILES command. 

Special File Handles 

PC DOS 7 provides five special file handles for use by application programs. 
The handles are: 

OOOOH Standard input device (STDIN) 

0001 H Standard output device (STDOUT) 

0002H Standard error device (STDERR) 

0003H Standard auxiliary device (STDAUX) 

0004H Standard printer device (STDPRN) 

File handles associated with standard devices do not need to be opened by a 
program, but a program can close them. STDIN should be treated as a 
read-only file. STDOUT and STDERR should be treated as write-only files. 
STDIN and STDOUT can be redirected. Function calls 01 H through OCR 
access the standard devices. 

The standard device handles are useful for performing I/O to and from the 
console device. For example, you can read input from the keyboard using 
the read function call (3FFI) and file handle OOOOFI (STDIN); you can also write 
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output to the console screen with the write function call (40H) and file handle 
0001 H (STDOUT). 

If you want to prevent redirection of your output to STDOUT, you can send it 
using file handle 0002H (STDERR). This facility also is useful for error 
messages or prompts to the user. 


Reading and Writing Data to a Fiie 

PC DOS 7 provides five functions to allow reading and writing to a file or 
device, specifying the offset within a file at which the read or write is to 
occur, and verifying the read-after-write state. The verification operation, 
however, slows performance. 


Activity 

Function 

Number 

Reading from a fiie or device 

3FH 

Writing to a file or device 

40H 

Specifying the address (through the pointer) at which a read or write is 
to occur 

42H 

Requesting the read-after-write state 

54H 

Specifying the read-after-write state 

2EH 


Requesting and Specifying Fiie Attributes 

While a file is being created, your program can specify certain attributes; for 


example, the date and time of creation and level of access. 

Activity 

Function 

Number 

Requesting and specifying a file's attributes 

43H 

Requesting and specifying a file's date and time 

57H 


Accessing Subdirectories 

Subdirectories, that is, directories other than the root directories, are files. 
There is no limit to the number of subdirectory entries if the physical media 
can accommodate them. All directory entries are 32 bytes long. 

Note: Values are in hexadecimal. 
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Each entry in the root directory consists of 32 bytes that are described in the 
figure foiiowing: 

OOH 

OSH 

OBH 
OCH 

16H 
18H 
lAH 
ICH 

20H 


Filename 


Extension 


File Attribute 


Reserved 


Time created or last updated 


Date created or last updated 


Starting Cluster 


File Size (4 bytes) 


The Filename 

Bytes 0 through 7 represent the fiiename. The first byte of the fiiename 
indicates the status of the fiiename. The status of a fiiename can contain the 
foiiowing vaiues: 

OOH Fiiename never used. To improve performance, this vaiue is used to 
iimit the iength of directory searches. 

OSH The first character of the fiiename has an E5H character. 

E5H Fiiename has been used, but the fiie has been erased. 
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2EH The entry is for a directory, if the second byte is aiso 2EH, the ciuster 
fieid centains the ciuster number of this directory's parent directory. 
(Ciuster number OOOOH is specified if the parent directory is the root 
directory.) 

Any other character is the first character of a fiiename. 

Note: Byte offsets are in decimai. 


The Filename Extension 

Bytes 8 through 10 indicate the fiiename extension. 

The File Attribute 

Byte 11 indicates the fiie's attribute. The attribute byte is mapped as foiiews: 

01 H indicates a read-oniy fiie. An attempt to open the fiie for output using 
function caii SDH or 6CH resuits in an errer code being returned. 

02H indicates a hidden fiie. The fiie is exciuded frem nermai directory 
searches. 

04H indicates a system file. The file is excluded frem normal directory 
searches. 

OSH Indicates the entry contains the volume label in the first 11 bytes. The 
entry contains no other usable informatien and may exist only in the 
reot directory. 

10H Indicates the entry defines a subdirectory and is excluded from normal 
directory searches. 

20H Indicates an archive bit. The bit is set ON when the file has been 
written to and closed. It is used by the BACKUP and RESTORE 
cemmands for determining whether the file has been changed since it 
was created er last updated. This bit can be used along with other 
attribute bits. 

All other bits are reserved and must be 0. 

The File Creation/Last Changed Time 

Bytes 22 and 23 contain the time when the file was created or last updated. 

The time is mapped in the bits as fellows: 

<23 > < 22 > 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 
hhhhhmmmmmmxxxxx 

Where: 
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hh = the binary number of hours (0-23) 
mm = the binary number of minutes (0-59) 

XX = the binary number of two-second increments 


The time is stored with the ieast significant byte first. 

The File Creation Date 

Bytes 24 and 25 contain the date when the fiie was created or iast updated. 
The date [mm/dd/yy) is mapped in the bits as foiiows: 

<25 > < 24 > 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

yyyyyyynimmmddddd 

Where: 

yy = 0-119 (1980-2099) 
mm = 1-12 
dd = 1-31 

The date is stored with the ieast significant byte first. 

The Starting Cluster Number 

Bytes 26 and 27 contain the ciuster number of the first ciuster in the fiie. The 
first ciuster for data space on ali hard disks and diskettes is ciuster 002. The 
ciuster number is stored with the ieast significant byte first. 

<27 > < 26 > 

0000000000100001 

The File Size 

Bytes 28 through 31 contain the fiie size in bytes. The first word contains the 
iow-order part of the size. Both words are stored with the ieast significant 
byte first. 


Accessing Directories 

PC DOS 7 provides four functions within interrupt 21 H to create, identify, 
change or deiete directories. 



Function 

Activity 

Number 

Removing a subdirectory 

3AH 

Creating a subdirectory 

39H 

Changing to another directory 

3BH 

identifying the current directory 

47H 
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Finding Fiies in Directories 

PC DOS 7 provides two functions within interrupt 21 H to search for the first 
matching entry and the next matching entry. 



Function 

Activity 

Number 

Searching for the first matching entry 

4EH 

Searching for the next matching entry 

4FH 


Requesting and Specifying Nationai Language Support (NLS) 


PC DOS 7 provides the foiiowing functions for NLS: 



Function 

Activity 

Number 

Specifying the current country 

38H 

Requesting the country dependent information 

38H 

Providing doubie-byte character set (DECS) support 

65H 


Controiiing Network Operations 

Severai PC DOS 7 function caiis accept a network path as input if the iBM PC 
Locai Area Network support is ioaded. if network access is avaiiabie, further 
information is noted in the "Comments" section under each reievant function 
caii in Appendix B, “PC DOS 7 Function Caiis” on page 133. 

A network path consists of an ASCII string containing a computer name, a 
directory path, and an optionai fiiename. The network path cannot contain a 
drive specifier. The path is terminated by a byte of binary O's. Foiiowing is 
an exampie: 

SERVER1LEVEL1LEVEL2FILE1 

Many function caiis that accept an ASCliZ string as input accept a network 
path, if you want to execute function 5BH (Create a New Fiie), for exampie, 
you must have Read/Write/Create or Write/Create access to the directory to 
be abie to create a fiie. If you have Read Only or Write Oniy access and no 
Create access, you cannot create a fiie in the directory. Two function caiis 
that do not accept a network path as input are Change Current Directory 
(3BH) and Find First Matching Fiie (4EH). 
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The following function calls are available to control network operations: 


Activity 

Function 

Number 

Locking and unlocking read/write access to a region of a file 

5CH 

Writing ali data from a fiie to a device 

68H 

Requesting the local computer ID 

5E00H 

Specifying the printer setup string 

5E02H 

Requesting the printer setup string 

5E03H 

Requesting redirection 

5F02H 

Attaching to a redirect device 

5F03H 

Canceling redirection 

5F04H 
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Chapter 4. Accessing Files Using File Control Blocks 


This chapter provides guide and system architecture information to assist in 
performing the foiiowing tasks: 

• Accessing fiies 

• Accessing sequentiai records 

• Accessing random records 

• Finding fiies in directories 


The File Control Block (FCB) 

With few exceptions, a program shouid maintain fiies using Fiie Controi 
Biocks (FCBs) oniy to run under DOS 1.10. Fiie handies are the 
recemmended method for accessing fiies. 

One FCB maintained by your program and PC DOS 7 is required for each 
open fiie. Your program must suppiy a pointer to the FCB and fiii in the 
appropriate fieids required by specific function caiis. 

A program shouid not attempt te use the reserved fieids in the FCB. Bytes 0 
through 15 and 32 through 36 must be set by the user program. Bytes 16 
threugh 31 are set by PC DOS 7 and must not be changed by user programs. 

An unopened FCB consists of the FCB prefix (if used), the drive number, the 
fiiename, and the extensions appropriateiy specified. An epen FCB is one in 
which the remaining fieids have been specified by the create or open 
function caiis. 

Aii word fieids are stored with the ieast significant byte first. Fer exampie, a 
recerd iength of 128 is stored as 80H at effset 14, and OOFi at offset 15. 

Figure 2 on page 24 gives further expianation. 
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-7 


hex FF 


Zeros 


Attribute 


Dri ve 

Filename (Sbytes 

or reserved device name 




Filename extension 

Current block 

Record size 

File size 
(low part) 

File size 
(high part) 

Date 




Reserved for system use 



Current 

record 


Random record Random record 
number (low pt) number (high pt) 


FCB 

extension 

Standard 

FCB 


Figure 2. The File Control Block 

Areas 16 through to 31 are filled in by DOS and must not be modified. 

Other areas are filied in by the using program. 

Note: Offsets are in decimal. 

The FCB is formatted as foiiows: 

Drive Number 

Byte 0 represents the drive number. For example, before the file is opened, 
0 equais the defauit drive, 1 equais drive A, and 2 equais drive B. After the 
file is opened, 0 equais drive A, 1 equais drive A, and 2 equais drive B. 

The actuai drive number replaces the 0 when a file is opened. 

Filename 

Bytes 1 through 8 represent the filename, left-justified with traiiing bianks. if 
a reserved device name such as LPT1 is specified here, do not inciude the 
coion. 
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Filename Extension 

Bytes 9 through 11 represent the filename extension, left-justified with trailing 
blanks or all blanks. 

Current Block Number 

Bytes 12 through 13 represent the current block number relative to the 
beginning of the file, starting with 0. The 0 is set by the open function call. A 
block consists of 128 records, each size specified in the logical record size 
field. The current block number is used with the current record field for 
sequential reads and writes. 

Logical Record Size 

Bytes 14 through 15 represent the logical record size in bytes. 80H is set by 
the open function call. If you want to change the logical record size from 
80H, you can reset the value. PC DOS 7 uses the value to determine 
locations in the file for all disk reads and writes. 

File Size 

Bytes 16 through 19 represent file size in bytes. In this two-word field, the 
first word is the low-order part of the size. 

File Date 

Bytes 20 through 21 represent the date the file was created or last updated. 
The date {mm/dd/yy) is mapped in the bits as follows: 

< 21 > < 20 
15 14 13 12 11 10 9 8 7 6 5 4 3 
yyyyyyymmmmdd 

where: 

yy is 0-119 (1980-2099) 
mm is 1-12 
dd is 1-31 

Reserved 

Bytes 22 through 31 are reserved. 

Record Number in Block 

Byte 32 represents the current relative record number (0-127) within the 
current block. You must set this field before doing sequential read and write 
operations to the diskette. This field is not initialized by the open function 
call. 


2 1 0 
d d d 


Chapter 4. Accessing Files Using File Control Blocks 25 



Record Number within File 

Bytes 33 through 36 represent the record number relative to the beginning of 
the file, starting with 0. You must set this field before doing random read 
and write operations to the diskette. This field is not initialized by the open 
function call. 

If the record size is less than 64 bytes, both words are used. If the record 
size is more than 64 bytes, only the first 3 bytes are used. Note that if you 
use the FCB at 5CH in the program segment, the last byte of the FCB 
overlaps the first byte of the unformatted parameter area. 

The Extended FCB 

The extended FCB is used to create or search in the disk directory for files 
with special attributes. The extension adds a 7-byte prefix to the FCB, 
formatted as follows: 

Extended FCB 

FCB byte -7 contains FFH to indicate an extended FCB. 

Reserved 

FCB bytes -6 to -2 are reserved. 

File Attribute 

FCB byte -1 represents an attribute byte. Function calls OOH through 2EFI are 
valid for both the standard FCB and the extended FCB. If you are using an 
extended FCB, the appropriate register should be set to the first byte of the 
prefix, rather than the drive number field. 

The Disk Transfer Area (DTA) 

PC DOS 7 uses a buffer in memory, the Disk Transfer Area (DTA), to hold the 
data for FCB file reads and writes. The DTA can be at any location within 
the data area of your program and should be specified by your program. 

Only one DTA can be in effect at a time, so your program must tell PC DOS 7 
which memory location to use before issuing disk read or write functions. 
When a program is given control by COMMAND. COM, a default DTA large 
enough to hold 128 bytes is established at 80H in the program segment 
prefix. 

PC DOS 7 provides the following functions within interrupt 21 H to handle DTA 
activities: 
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Function 

Activity 


Number 

Specitying the buffer address for 

reading and writing data in the DTA 

1 AH 

Requesting the butter address for 

reading and writing data in the DTA 

2FH 


Accessing Files 

An FCB can identify a fiie on any valid drive, but only in the current directory 
of the specified drive. 

If SHARE has not been loaded, the number of files that can be open at a time 
(using FCB function calls) is not restricted. When file sharing is loaded, 
however, the maximum number of FCB opened files is limited by the value 
specified in the FCBS command in CONFIG.SYS. The m value specifies the 
total number of files that can be opened by FCBS. 

When the maximum number of FCB opens is exceeded, PC DOS 7 
automatically closes the least recently used file. Any attempt to access such 
a file results in the interrupt 24H critical error message, “FCB not available.” 
If this situation occurs while a program is running, the value specified for m 
in the FCBS command should be increased. 

Do not use the same FCB to open a second file without closing the first open 
file. If more than one file is to be opened concurrently, use separate FCBs. 
To avoid potential file sharing problems, close files after I/O is performed. 
Close the file before trying to delete or rename an open file. 

Managing files using the FCBS command can be performed using the 
follewing functien calls: 


Activity 

Function 

Number 

Opening a file 

OFH 

Closing a file 

10H 

Deleting a file 

13H 

Creating a file 

16H 

Renaming a file 

17H 

Requesting the file size 

23H 

Separating the filename information into its components (parsing) 

29H 
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Accessing Sequential Records 

By using the current block, current record, and record length fields of the 
FCB, you can perform sequential I/O by using the following sequential read 
or write function calls within interrupt 21 H: 



Function 

Activity 

Number 

Reading from a record 

14H 

Writing to a record 

15H 


Accessing Random Records 

Random I/O can be performed by filling in the random record and record 
length fields in the FCB and issuing the following function calls within 
interrupt 21 H: 


Activity 

Function 

Number 

Reading from a single record 

21 H 

Writing to a single record 

22H 

Specifying the random record fieid in the FCB 

24H 

Reading from muitipie records 

27H 

Writing to muitipie records 

28H 


Finding Files in Directories 

Using the FCB as a source, finding and changing files in directories is 
performed by the following functions within interrupt 21 H: 


Activity 

Function 

Number 

Searching for the first matching fiie entry 

1 1 H 

Searching for the next matching fiie entry 

12H 

Deieting a fiie 

13H 

Creating a fiie 

16H 

Renaming a fiie 

17H 

Separating the fiiename information into its components (parsing) 

29H 
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Chapter 5. Managing Device i/0 


This chapter provides guide and system architecture information about the 
foiiowing tasks: 

• Managing dispiay i/0 

• Managing keyboard i/0 

• Managing misceiianeous i/0 

• Managing fiie system activities 

• Accessing the system device drivers' controi channei. 


Managing Display I/O 

PC DOS 7 provides four functions within interrupt 21 H that send characters or 
strings of characters to the screen. 


Activity 

Function 

Number 

Outputting a character to the screen, with the ability to trigger the 
control-break interrupt handler 

02H 

Waiting until a character is input and outputting it to the screen without 
the ability to trigger the control-break interrupt handler 

06H 

Outputting a string of characters in memory to the screen 

09H 

Outputting a string of characters in a buffer to the screen or writing the 
string to a file device 

40H 


For further information on specifying character attributes, foreground and 
background screen coiors, and screen size using ANSi.SYS, see the PC DOS 
7 User's Guide and Reference. 


Managing Keyboard I/O 

PC DOS 7 provides a fuil compiement of functions within interrupt 21 H that 


your application program can use to manage keyboard I/O. 

Activity 

Function 

Number 

Sending input from the keyboard (with echo) to the display 

01 H 

Receiving input directly from the keyboard, or sending output directly to 
the display 

06H 

Receiving input directly from the keyboard without echo 

07H 
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Activity 

Function 

Number 

Receiving input from the keyboard without echo to the display with the 

08H 

ability to trigger the control-break interrupt handler 


Reading characters from the keyboard to the buffer 

OAH 

Checking the keyboard buffer status 

OBH 

Clearing the keyboard buffer; specifying which function to call after 

OCH 

clearing the buffer 



For further information on reassigning the keys using ANSI. SYS, see the PC 
DOS 7 User's Guide and Reference. 


Managing Miscellaneous I/O 

Three functions are available to manage miscellaneous I/O. 



Function 

Activity 

Number 

Receiving auxiliary input 

OSH 

Sending auxiliary output 

04H 

Printing output 

OSH 


Managing File System Activities 

The following system activities are supported by PC DOS 7: 


Activity 

Function 

Number 

Requesting the local computer ID 

5E00H 

Specifying the printer setup string 

5E02H 

Requesting the printer setup string 

5E03H 

Requesting redirection list 

5F02H 

Attaching to a redirect device 

5F03H 

Canceling redirection 

5F04H 

Writing all data from a file to a device 

68H 
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Accessing the System Device Drivers" Controi Channei 

Function 44H within interrupt 21 H is a muiti-purpose function for accessing 
the device drivers' controi channei. Using function 44H, your appiication 
program can request the status of a device and read and write to the I/O 
controi channei. The foiiowing subfunction vaiues shouid be passed in AL: 


Category 

Activity 

Subfunction 

Number 

Requesting and specifying device 

Requesting device information 

OOH 

I information | 


Specifying device informafion 

01 H 

Reading and writing data to a 

Reading from a character device 

02H 

character device 


Writing to a character device 

OSH 

Reading and writing data to a 

Reading from a block device 

04H 

biock device 


Writing to a block device 

OSH 

Requesting and specifying device 

Determining whether a device 

OSH 

information 

contains removable media 


Providing network support for 

Determining whether a logical 

OOH 

devices 

device is local or remote 



Determining whether a file handle 
is local or remote 

OAH 


Specifying how many times (and 
intervals) PC DOS 7 should try to 
resolve shared file conflicts 

OBH 


Controlling I/O for file handles 

OCH 


Controlling I/O for block devices 

ODH 

Requesting and specifying the 

Requesting the logical drive 

OEH 

I logical drive | 


Specifying the logical drive 

OFH 


Chapter 5. Managing Device i/0 31 




Reading and Writing Data in Binary and ASCII Modes 

A program can use function 44H to change the mode in which data is read or 
written to a device. If I/O is performed in binary mode, controi vaiues have 
no meaning, if I/O is performed in ASCII mode, certain controi vaiues have 
meaning. They are shown in the foiiowing tabie: 


Control 

Keyboard 


Value 

Input 

Meaning 

OSH 

aC 

Control Break 

04H 

aD 

End of Task 

10H 

aP 

Print Screen 

1 1 H 

aQ 

Scroll restart 

13H 

aS 

Scroll Lock 

OAH 

aJ 

Line Feed 

ODH 

aM 

Carriage Return 

1 AH 

aZ 

End-Of-Fiie 


When a fiie is read in ASCII mode, it is echoed to the dispiay and tabs are 
expanded into spaces. They are ieft as a tab byte (09H) in the input buffer. 
When a fiie is written in ASCII mode, tabs are expanded to 8-character 
boundaries and filied with spaces (20H). 
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Chapter 6. Controlling Processes 


This chapter provides guide and system architecture information about the 
foiiowing activities: 

• Aiiocating memory 

• identifying a program at ioad time 

• Loading and executing overiays 

• Terminating a program/subprogram 

• Loading an overiay without executing it 

• Caiiing a command processor 

• Responding to errors 

• Responding to a controi-break action 

• Requesting and specifying the system date and time 

• Requesting and specifying the interrupt vectors. 


Allocating Memory 

PC DOS 7 keeps track of aiiocated and avaiiabie memory biocks and 
provides three function caiis for appiication programs to communicate their 
memory requests. 



Function 

Activity 

Number 

Allocating memory 

48H 

Freeing allocated memory 

49H 

Changing the size of blocks of allocated memory 

4AH 


PC DOS 7 Memory Management 

PC DOS 7 manages memory by allocating 16-byte units called paragraphs 
and building a control block for each allocated block. Any allocation is 16 
bytes larger than the actual request because PC DOS 7 automatically 
allocates a control block to keep track of each allocated block. 

When the user starts the program at the command line, COMMAND.COM 
loads the executable program module Into the largest unused block of 
available memory and reads the file header. If there Is not enough memory 
available, the system returns an error code and passes control to the 
program. Your program should use the SETBLOCK function call (4AH) to 
reduce allocated memory to the size It needs. 
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Note: Because it is iikeiy that the defauit stack suppiied by PC DOS 7 iies in 
the area of memory being freed, a .COM program shouid remember to 
set up its own stack before issuing a SETBLOCK. The SETBLOCK oaii 
frees unneeded memory whioh then can be used for ioading 
subsequent programs. 

If your program requires additionai memory during processing, issue function 
cail 48H within interrupt 21. To free memory, issue function caii 49H within 
interrupt 21 . 

The PC DOS 7 Memory Map 

The foiiowing tabie iliustrates the order in which PC DOS 7 components and 
appiication programs are iooated in memory when PC DOS 7 is ioaded iow 
and no HMA exists. 


Location 

Use 

0000:0000 

Interrupt vector table 

0040:0000 

ROM communication area 

0050:0000 

PC DOS 7 communication area 

0070:0000 

IBMBIO.COM - PC DOS 7 interface to ROM I/O routines 

XXXX:0000 

IBMDOS.COM - PC DOS 7 interrupt handlers, service routines (INT 21 
functions) 

XXXX:0000 

PC DOS 7 buffers, control areas, and installed device drivers 

XXXX:0000 

Resident portion of COMMAND.COM - Interrupt handlers for interrupts 
22H (terminate), 23H (Ctrl-Break), 24H (critical error), and code to reload 
the transient portion 

XXXX:0000 

External command or utility - .COM or .EXE file 

XXXX:0000 

User stack for .COM files 

XXXX:0000 

Transient portion of COMMAND.COM 


The foliowing tabie iiiustrates the order in which the PC DOS 7 components 
and appiication programs are iocated in memory when PC DOS 7 is ioaded 
high. 


Location 

Use 

0000:0000 

Interrupt vector table 

0040:0000 

ROM communication area 

0050:0000 

PC DOS 7 communication area 

0070:0000 

Resident BIOS data - also including device driver headers and entry 
points 

XXXX:0000 

PC DOS 7 data 
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Location 

Use 

XXXX:0000 

PC DOS 7 installable device drivers and data structures that are 


allocated by SYSINIT 

FFFF:0010 

VDISK header (see note below) 

FFFF:0030 

IBMBIO 

XXXXiXXXX 

IBMDOS 


Memory map addresses are in segmentioffset format. For example, 
0070:0000 is absolute address 00700H. 

Note: The VDISK header is placed at the start of the HMA as a precaution 
because most INT 15 allocations respect VDISK headers. 

The PC DOS 7 Communication Area is used as follows: 

0050:0000 Print screen status flag store 

0 Print screen not active or successful print screen operation 

1 Print screen in progress 

255 Error encountered during print screen operation 
0050:0001 Used by BASICA 
0050:0004 Single-drive mode status byte 

0 Diskette for drive A was last used 

1 Diskette for drive B was last used 
0050:0010—0021 Used by BASICA 

0050:0022 — 002F Used by PC DOS 7 for diskette initialization 
0050:0030 — 0033 Used by MODE command. 

All other locations within the 256 bytes beginning at 0050:0000 are reserved 
for PC DOS 7 use. 
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Identifying a Program at Load Time 

PC DOS 7 provides two function cails for appiication programs to specify and 
identify themseives at ioad time: 




Function 

Activity 


Number 

Creating the means for PC DOS 7 to identify a program 

at load time 

26H 

through the program segment prefix (PSP) 



Requesting how PC DOS 7 identified a program at ioad 

time 

62H 


The Program Segment 

When you enter an externai command or cali a program with the EXEC 
function caii (4BH), PC DOS 7 determines the iowest avaiiabie address in 
memory and assigns it to the program. That area of memory is caiied the 
program segment. At offset 0 within the program segment, PC DOS 7 buiids 
a program segment prefix controi biock. When an EXEC is issued, PC DOS 7 
ioads the program at offset 100H and gives it controi. See Figure 3 on 
page 37 for an iliustration of the program segment prefix. 
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0 

1 

2 

3 

4 

5 

6 

7 

1 1 
INT 

20H 

1 

Top of 
memory 

Reserved 

8 

9 

A 

B 

c 

D 

E 

F 

Reserved 

1 

Termi nate 
address 

IP 

1 

1 

Termi nate 
address 

CS 

1 

Ctrl -break 
exit address 

IP 

10 

11 

12 

13 

14 

15 

16 

17 

Ctrl -break 
exit address 

CS 

Critical error 
exit address 

IP CS 

Reserved 

18 to 2B 

2C 

2D 

2E 

2F 

Reserved 

Envi ronment 
poi nter 

Reserved 

30 to 4F 

Reserved 

50 

51 

52 

53 

54 

55 

56 

57 

DOS call 

Reserved 

58 

59 

5A 

5B 

5C 

5D 

5E 

5E 

Reserved 

Unopened Standard FCBl 

60 

61 

62 

63 

64 

65 

66 

67 

Unopened Standard FCBl (continued) 

68 

69 

6A 

6B 

6C 

6D 

6E 

6E 

Unopened Standard FCBl 
(conti nued) 

Unopened Standard FCB2 

70 

71 

72 

73 

74 

75 

76 

77 

Unopened Standard FCB2 (continued) 

78 

79 

7A 

7B 

7C 

7D 

7E 

7E 

Unopened Standard FCB2 (continued) 

80 

81 

82 

83 

84 

85 

86 

87 

Param 

Length 

1 

Command parameters 

starting with leading blanks j 

1 

F8 

F9 

FA 

FB 

FC 

FD 

FE 

FF 

1 1 
1 

j Command parameters 

1 


Figure 3. The Program Segment Prefix 
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The program segment prefix's first segment of avaiiabie memory is in 
paragraph form; that is, 1000H represents 64KB. The word at offset 6 
contains the number of bytes avaiiabie in the segment. 

Offset 2CH contains the environment's paragraph address. 

Offset 50H contains code to invoke the PC DOS 7 function dispatcher. By 
placing the desired function number in AH, a program can issue a long call 
to PSP+50H to invoke a PC DOS 7 function rather than issuing an interrupt 
21H. 

The default disk transfer address is set to 80H. 

An unformatted parameter area at 81 H contains all the characters entered 
after the command name, including leading and imbedded delimiters, with 
80H set to the number of characters. If the <, >, or | parameters were 
entered on the command line, they and the filenames associated with them 
will not appear in this area because redirection of standard input and output 
is transparent to applications. 

For .COM files, offset 6 (one word) contains the number of bytes available in 
the segment. 

Register AX contains the drive specifiers entered with the first two 
parameters as follows: 

AL=FFH if the first parameter contained an invalid drive specifier 
(otherwise AL=00H). 

AH = FFH if the second parameter contained an invalid drive specifier 
(otherwise AH = 00H). 

In .EXE programs DS and ES registers are set to point to the program 
segment and CS, IP, SS, and SP registers are set to the values passed by the 
Linker. 

In .COM programs all four segment registers contain the segment address of 
the initial allocation block, starting with the program segment prefix control 
block. The instruction pointer (IP) is set to 100H. The SP register is set to 
the end of the program's segment. The segment size at offset 6 is rounded 
down to the paragraph size. 
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Loading and Executing Overiays 

Your program can use the 4BH function call to load optional overlays. 
Function 4BH, value 0, loads and executes a program with overlays. 

Function 4BH, value 3, loads an overlay without executing it. 

If your program calls an overlay, the EXEC call assumes the calling program 
has already allocated memory for the overlay. The request to load an 
overlay does not verify that the calling program owns the memory Into which 
the overlay Is to be loaded. An overlay leaded into memory not allocated to 
It can damage the PC DOS 7 memory management control blocks. This will 
not be evident until PC DOS 7 needs to use Its series ef centrol blocks. 

If a memory allocation error is returned, the problem must be corrected and 
the system restarted. Overlays should not Issue SETBLOCK calls because 
they do not own the memory In which they operate. The memory is 
controlled by the calling program. 

The Parameter Biock 

When your program calls a subprogram using the EXEC call (4BFI), It can 
pass a parameter block which provides the subprogram with the following: 

• The environment string 

• A command line which permits it to act like another command processor 

• File control blocks at 5C and 6C In the program segment prefix 
(cptlonal). 

The Environment String 

The envircnment passed from the calling program Is a copy of Its 
environment. The segment address of the passed envircnment Is contained 
at offset 2CFI In the program segment prefix. 

The environment is a series of ASCII strings totaling less than 32KB In the 
form: 

NAME=parameter 

Note: NAME= Is always In uppercase. 

Each string is terminated by a byte of O's. The complete series of strings is 
terminated by another byte of O's. Another ASCII string containing the word 
count and an ASCIIZ string containing the executable program's drive, path, 
filename, and extension follow the series of environment strings. 

The environment built by the command processor and passed to all called 
programs contains a COMSPEC= string, the last PATH, APPEND and 
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PROMPT commands issued, and any environment strings specified with the 
SET command. 


The Command Line 

Your program must create a command iine which wili be transferred to the 
subprogram. 

The File Control Blocks 

If your program is using files based on file handles, the file control blocks are 
of no concern. If your program is using file control blocks, and either 5CH or 
6CH contain a pathname, the corresponding FCB will contain only a valid 
drive number. The filename field will not be valid. 


Terminating a Program/Subprogram 

PC DOS 7 provides four functions and two interrupts to terminate programs. 
It also provides an interrupt to permit your program to specify where control 
is to be passed upon termination. 


Activity 

Function 

Number 

Terminating a program 

OOH 

Terminating a program with a specified portion remaining in memory 

31 H 

Terminating a program and passing controi to the caliing process 

4CH 

Determining how a process ended 

4DH 


Interrupt 20H terminates a program. Interrupt 27H terminates a program with 
a specified portion remaining in memory. Interrupt 22H specifies where 
control is to be passed upon program termination. 

When a subprogram terminates, control is returned to the calling program. 
Before terminating, the calling program must return to the system the 
memory it allocated to the subprogram. When the calling program 
terminates, control is returned to PC DOS 7. PC DOS 7 does a CHECKSUM 
to determine if the transient portion of COMMAND.COM has been modified. 

If it has, PC DOS 7 reloads COMMAND.COM based on the path specified in 
the environment. 

The program returns from executing in one of the following methods: 

• By a jump to offset 0 in the program segment prefix 

• By issuing an INT 20H 

• By issuing an INT 21 H with register AH=OOH or 4CH 
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• By calling location 50H in the program segment prefix with AH=00H er 
4CH. 

Using INT 21 H is the preferred methed. All programs must ensure that the 
CS register contains the segment address of the program segment prefix 
when terminating using any of the preceding methods except call 4CH. 

All of the preceding methods return control to the program that issued the 
EXEC. During the process, interrupt vectors 22H, 23H, and 24H (terminate, 
Ctrl-Break, and critical error exit addresses) are restored from the values 
saved in the program segment prefix of the terminating program. Control is 
then given to the terminating address. 


Loading an Overlay without Executing It 

If AL=3 is specified within function call 4BH, no program segment prefix is 
built, and DOS assumes the calling program has allocated memory for the 
overlay. The calling program should provide memory in one of two ways: 

• Provide enough memory for the overlay when it issues the SETBLOCK 
call {4AH) 

• Free adequate memery with the 49H call. 

When DOS receives an AL=3 request, the system assumes that the 
requested memory is owned by the calling pregram. As in subprograms, an 
overlay can be loaded into memory not allocated to it and damage the series 
of DOS memory management control blocks. 

Programs loaded with AL=3 should not issue the SETBLOCK call (4AH) 
because the memory in which they operate is owned by the calling process, 
not the overlay. Before terminating, the calling program must return to the 
system the memory it allocated to the overlay. When the calling program 
terminates, control is returned to DOS. 


Calling a Command Processor 

To call a command processor, you must do the follewing: 

• Assure that adequate free memory is available to contain the second 
copy of the command processor and the command it is to execute. Issue 
function call 4AH to shrink allocated memory to your current 
requirement. Issue function call 48H with BX=FFFFH. The return is 
available memory. 

• Build a parameter string for the secondary command processor in the 
form: 


Chapter 6. Controlling Processes 41 




1 byte = length of parameter string 
XX byte = parameter string 
1 byte = ODH (carriage return) 

For example, the following assembly statement builds the string to 
execute a DISKCOPY command: 

DB 19, '7C C:DISKCOPY A: B:" , 13 

• Use the EXEC function call (4BH, function value 0) to execute the 
secondary copy of the command processor. The COMSPEC = 
parameter in the environment passed at PSP+2CH identifies the drive, 
directory, and command processor name. Remember to set offset 2 in 
the EXEC control block to point to the parameter string. 


Responding to Errors 

When a PC DOS 7 function cannot be performed (indicating a critical error 
situation) control is transferred to interrupt 24H. Function 59FI provides 
additional information on the error condition. 


Activity 

Number 

Responding to a critical error situation 

Interrupt 24H 

Requesting additional error information and suggested action 

Function 59H 


Handle function calls report an error by setting the carry flag and returning 
the error code in AX. FCB function calls report an error by returning FFH in 
AL. 

The Extended Error function call (59H) provides a common set of error codes 
and specific error information such as error classification, location, and 
recommended action. In most critical cases, applications can analyze the 
error code and take specific action. Recommended actions are intended for 
programs that do not understand the error codes. Programs can take 
advantage of extended error support both from interrupt 24H critical error 
handlers and after issuing interrupt 21 H function calls. Do not code to 
specific error codes. 


Responding to a Control-Break Action 

Interrupt 23H is issued if a Ctrl-Break occurs during standard I/O. Function 
calls 09H and OAH can be used if there is a aC, carriage return and line feed 
produced as output. 
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Activity 

Function 


Number 

Displaying string 

09H 

Buffering keyboard inpuf 

OAH 

Responding to a control-break action 

23H 


If a Ctrl-Break is entered during standard input, standard output, standard 
printer, or asynchronous communications adapter operations, an INT 23H is 
executed, if BREAK is on, iNT 23H is checked on most function caiis, except 
06H and 07H. 

The user-written Ctri-Break routine can use function caiis 09H, OAH, and ODH 
to respond to the Ctri-Break action by having ^C, carriage return, and iine 
feed produced as output. ASCil codes ODH and OAH represent carriage 
return and iine feed, respectiveiy. If the Ctri-Break routine saves all 
registers, it may end with an IRET (return from interrupt) instruction to 
continue program execution. If the routine returns with a long return, the 
carry flag is used to determine whether or not to stop execution. If the carry 
flag is not set, execution continues, as with an IRET. 

There are no restrictions on what the Ctri-Break handler is allowed to do, 
providing the registers are unchanged if IRET is used. 


Chapter 6. Controlling Processes 43 




Requesting and Specifying the System Date and Time 

The following functions get or set the system date and time: 



Function 

Activity 

Number 

Requesting the system date 

2AH 

Specifying the system date 

2BH 

Requesting the system time 

2CH 

Specifying the system time 

2DH 


Requesting and Specifying the Interrupt Vectors 

A program can create and change the centents of the interrupt vectors, the 
4-byte addresses of the routines in memory that service hardware and 
software interrupts. On exit, the program must reset the interrupt vectors to 
where they were pointing originally. 

If you want a program to examine or specify the centents of an interrupt 
vecter, use PC DOS 7 function calls 35H and 25H and avoid referencing the 
interrupt vector locations directly. 



Function 

Activity 

Number 

Specifying the interrupt vector value 

25H 

Requesting the interrupt vector value 

35H 
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Chapter 7. Debugging a Program 


This chapter describes how to use the DEBUG.COM program that is shipped 
as part of PC DOS 7 to identify and fix problems in your programs. 

Warning 

Use of the DEBUG program should not be undertaken lightly, the utility 
has the power to alter code, always ensure that you take a backup copy 
of the code that you will be using debug on. 


The DEBUG Utility 

DEBUG provides a controlled testing environment that enables you to 
monitor the execution of a program. You can make changes directly to a 
.COM or an .EXE file and execute the file Immediately to determine whether 
your changes fixed a problem. You do not need to reassemble source code 
files first. DEBUG allows you to load, alter, or display any file and to execute 
object files as well. 


Starting the DEBUG.COM Program 

To start DEBUG, enter information In the following format: 

DEBUG [[drive:][path]filename [testfil e-parameters]] 

You can enter just the DEBUG command, or you can include a file 
specification. The parameters parm1 and parm2 represent input and output 
specifications of the program you are debugging. For example, suppose you 
wanted to monitor the execution of the PC DOS 7 DISKCOMP utility. You 
enter: 

DEBUG DISKCOMP.COM A: B: 

The DEBUG program loads DISKCOMP Into memory and displays the DEBUG 
prompt: 


The hyphen (-) tells you DEBUG is ready to accept commands to alter, 
display, or execute the contents of the program In memory. 
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If you enter just DEBUG without a file specification, you can either work with 
the present memory contents or you can load a required file into memory 
using the DEBUG Name and Load commands. 


Entering Commands at the DEBUG Prompt 

A DEBUG command consists of a single letter, usually followed by one or 
more parameters. For example, the Name command is entered at the 
DEBUG prompt as a single letter followed by a file specification: 

-N MY PROG 

A command and its parameters can be entered in uppercase, lowercase, or 
a combination of both. The command and its parameters can be separated 
by delimiters; however, delimiters are only required between two 
consecutive hexadecimal values. Thus, the following Dump commands are 
equivalent: 

dcs:100 no 
d cs:100 no 
d,cs:100,n0 

A command is activated only after you press the Enter key. If you want to 
terminate a command and return to the DEBUG prompt, simultaneously 
press the Ctrl and Break keys. 

For commands producing a large amount of output, you can simultaneously 
press the Ctrl and Num Lock keys (or Pause key if available) to suspend the 
display and then press any key to restart the display, or you can redirect the 
command's output to a file. 

When DEBUG encounters a syntax error in a line, it displays the line with the 
error identified as follows: 

d cs:100 CS:100 

''error 110 

In this example, the Dump command expects the second address to contain 
only a hexadecimal offset value. It finds the S, which is not a hexadecimal 
character. 
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DEBUG Command Summary 

The table below lists the DEBUG commands and describes the debugging 
operations you can perform with them. Complete format descriptions and 
examples for each command can be found starting on page 49. 


Command 

Task Description 

A (Assemble) 

Assemble IBM Macro Assembler statements directly into 
memory. 

C (Compare) 

Compare the contents of two blocks of memory. 

D (Dump) 

Dump the contents of a portion of memory to the display or 
redirect it to a file. 

E (Enter) 

Make changes to bytes in memory. 

F (Eill) 

Fill a range of memory with byte values. 

G (Go) 

Execute the program in memory from one address to the 
breakpoint address and then display the next instruction. 

H (Hex) 

Add and subtract two hexadecimal values and display the 
results. 

1 (Input) 

Display the input in the first byte next to the port. 

L (Load) 

Load the contents of absolute disk sectors or a file specified 
by the Name command into memory. 

M (Move) 

Copy the contents of a block of memory to another location. 

N (Name) 

Set up file control blocks and file specification information for 

Load and Write commands. 

0 (Output) 

Send a byte to an output port. 

P (Proceed) 

Execute a subroutine call, loop instruction, interrupt, or repeat 
string instruction and return control to DEBUG at the next 
instruction. 

Q (Quit) 

End the DEBUG session without saving the debugged program. 

R (Register) 

Display the contents of registers and the settings of flags. 

S (Search) 

Search a range of memory for characters. 

T (Trace) 

Execute one or more instructions in your program and display 
the contents of registers and flags after each instruction. 

U (Unassemble) 

Translate the contents of memory into Assembler-like 
statements, displaying their addresses and hexadecimal 
values. 

W (Write) 

Write the debugged program to absolute disk sectors or to the 
original file loaded with DEBUG. 

XA (Allocate) 

Allocate a specified number of expanded memory pages to an 
EMS handle. 

XD (Deallocate) 

Deallocate an EMS handle. 

XM (Map) 

Map an EMS logical page to an EMS physical page from an 

EMS handle. 

XS (Status) 

Display the status of expanded memory. 
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The DEBUG Work Space 

When the DEBUG program starts, the registers and flags are set to the 
following values for the program being debugged: 

• The segment registers (CS, DS, ES, and SS) are set to the bottom of free 
memory; that is, the first segment after the end of the DEBUG program. 

• The Instruction Pointer (IP) is set to hex 0100. 

• The Stack Pointer (SP) is set to the end of the segment, or the bottom of 
the transient portion of the program loader, whichever is lower. The 
segment size at offset 6 is reduced by hex 100 to allow for a stack that 
size. 

• The remaining registers (AX, BX, CX, DX, BP, SI, and Dl) are set to 0. 
However, if you start the DEBUG program with a file specification, the CX 
register contains the length of the file in bytes. If the file is greater than 
64KB, the length is contained in registers BX and CX (the high portion in 
BX). 

• The initial state of the flags is: 

NV UP El PL NZ NA PO NC 

• The default disk transfer address is set to hex 80 in the code segment. 

All of available memory is allocated. At this point, the loaded program is 
unable to allocate memory. 

.EXE Files 

If a file loaded by DEBUG has an extension of .EXE, DEBUG does the 
necessary relocation and sets the segment registers, stack pointer, and 
instruction pointer to the values defined in the file. The DS and ES registers, 
however, point to the program segment prefix at the lowest available 
segment. The BX and CX registers contain the size of the program that is 
smaller than the file size. 

The program is loaded at the high end of memory if the appropriate 
parameter was specified when the linker created the file. 

.HEX Files 

If a file loaded by DEBUG has an extension of .HEX, the file is assumed to be 
in INTEL hex format, and is converted to executable form while being loaded. 
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A (Assemble) Command 


Purpose 

Assembles macro assembler language statements directly Into memory. 


Format 

A[ac/c/ress] 


Parameters 

address Use any of the following formats: 

• A segment register plus an offset, such as CS:0100 

• A segment address plus an offset, such as 4BA:0100 

• An offset only, such as 100. In this case, the default 
segment Is used. 


Comments 

All numeric input to the Assemble command Is In hexadecimal. The 
assembly statements you enter are assembled Into memory at successive 
locations, starting with the address specified in address. If no address Is 
specified, the statements are assembled into the area at CS:0100, if no 
previous Assemble command was used, or Into the location following the last 
Instruction assembled by a previous Assemble command. After all desired 
statements have been entered, press the Enter key when you are prompted 
for the next statement to return to the DEBUG prompt. 

DEBUG responds to Invalid statements by displaying: 

A error 

and re-displayIng the current assemble address. 

DEBUG supports standard 8086/8088 assembly language syntax (and the 8087 
Instruction set), with the following rules: 

• All numeric values entered are hexadecimal and can be entered as 1 
through 4 characters. 

• Prefix mnemonics are entered In front of the opcode to which they refer. 
They can also be entered on a separate line. 

• The segment override mnemonics are CS:, DS:, ES:, and SS:. 
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String manipulation mnemonics must specify the string size. For 
example, MOVSW must be used to move word strings and MOVSB must 
be used to move byte strings. 

The mnemonic for the far return is RETF. 

The assembler will automatically assemble short, near, or far jumps and 
calls depending on byte displacement to the destination address. These 
can be overridden with the NEAR or FAR prefix. For example: 

0100:0500 JMP 502 ; a 2 byte short jump 

0100:0502 JMP NEAR 505 ; a 3 byte near jump 

0100:0505 JMP FAR 50A ; a 5 byte far jump 

The NEAR prefix can be abbreviated to NE, but the FAR prefix cannot be 
abbreviated. 

DEBUG cannot tell whether some operands refer to a word memory 
location or a byte memory location. In this case, the data type must be 
explicitly stated with the prefix WORD PTR or BYTE PTR. DEBUG will also 
accept the abbreviations WO and BY. For example: 

NEG BYTE PTR [128] 

DEC WO [SI] 

DEBUG also cannot tell whether an operand refers to a memory location 
or to an immediate operand. DEBUG uses the common convention that 
operands enclosed in square brackets refer to memory. For example: 

MOV AX, 21 ; Load AX with 21H 

MOV AX, [21] ; Load AX with the contents of memory location 21H 

Two popular pseudo-instructions have also been included. The DB 
opcode assembles byte values directly into memory. The DW opcode 
assembles word values directly into memory. For example: 

DB 1,2, 3, 4, "THIS IS AN EXAMPLE" 

DB 'THIS IS A QUOTE: "' 

DB "THIS IS AN APOSTROPHE:'" 

DW 1000, 2000, 3000, "BACH:" 

All forms of the register indirect commands are supported. For example: 

ADD BX,34[BP+2][SI-1] 

POP [BP+DI] 

PUSH [SI] 

All opcode synonyms are supported. For example: 



LOOPZ 100 
LOOPE 100 

JA 200 

JNBE 200 

• For numeric co-processor opcodes the WAIT or FWAIT prefix must be 
expiicitiy specified. For exampie: 

FWAIT FADD ST,ST(3) ;This line will assemble a FWAIT prefix 
FLO TBYTE PTR [BX] ;This line will not 

Examples 

C>debug 

-a200 

08B4:0200 xor ax, ax 
08B4:0202 mov [bx],ax 
0884:0204 ret 
0884:0205 


C (Compare) Command 
Purpose 

Compares the contents of two biocks of memory. 

Format 

C range address 


Parameters 

range Either ef these two formats: 

• An address foiiowed by an offset, such as CS:100 110. 

• An address foiiowed by L value, where value is the number 
of hexadecimai bytes to be processed. For exampie, CS:100 
L 10. 

The iimit fer range is hexadecimai 10000 or decimai 64KB. To 
specify a range of 64KB within 4 hexadecimai characters, enter 
0000 or 0 for value. 
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address 


Any of these three formats: 


• A segment register plus an offset, such as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment Is used. 


Comments 

The contents of the two blocks of memory are compared; the length of the 
comparison Is determined from the range. If unequal bytes are found, their 
addresses and contents are displayed. In the form: 

addrl bytel byte2 addr2 

where, the first half (addrl bytel) refers to the location and contents of the 
mismatching locations in range, and the second half (byte2 addr2) refers to 
the byte found In address. 

If you enter only an offset for the beginning address of range, the C 
command assumes the segment contained In the DS register. To specify an 
ending address for range, enter It with only an offset value. 


Examples 

C 100 L20 200 

The 32 bytes (hex 20) of memory beginning at DS:100 are compared with the 
32 bytes beginning at DS:200. L20 is the range. 


D (Dump) Command 
Purpose 

Displays the contents of a portion of memory. 

Format 

D [ac/cf/'ess] 
or 

D {range] 
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Parameters 

address Any of the following formats: 

• A segment register plus an offset, such as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment is used. 

range Either of these two formats: 

• An address followed by an offset, such as CS:100 110. 

• An address followed by L value, where value is the number 
of hexadecimal bytes to be processed. For example, CS:100 
L 10. 

The limit for range is hexadecimal 10000 or decimal 64K bytes. 
To specify a range of 64K bytes within 4 hexadecimal 
characters, enter 0000 or 0 for value. 

Comments 

The dump is displayed in two parts: 

1. A hexadecimal portion. Each byte is displayed in hexadecimal. 

2. An ASCII portion. The bytes are displayed as ASCII characters. 
Unprintable characters (ASCII 0 to 31 and 127 to 255) are indicated by a 
period. 

With a 40-column system display format, each line begins on an 8-byte 
boundary and shows 8 bytes. 

With an 80-column system display format, each line begins on a 16-byte 
boundary and shows 16 bytes. There is a hyphen between the 8th and 9th 
bytes. 

Note: The first line may have fewer than 8 or 16 bytes if the starting address 
of the dump is not on a boundary. In this case, the second line of the 
dump begins on a boundary. 

The Dump command has two format options. 

Option 1 

Use this option to display the contents of hex 40 bytes (40-column mode) or 
hex 80 bytes (80-column mode). For example: 
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D address 


or 


D 

The contents are dumped starting with the specified address. 

If you do not specify an address, the D command assumes the starting 
address is the location following the last location displayed by a previous D 
command. Thus, it is possible to dump consecutive 40-byte or 80-byte areas 
by entering consecutive D commands without parameters. 

If no previous D command was entered, the location is offset hex 100 into the 
segment originally initialized in the segment registers by DEBUG. 

Note: If you enter only an offset for the starting address, the D command 
assumes the segment contained in the DS register. 

Option 2 

Use this option to display the contents of the specified address range. For 
example: 

D range 

Note: If you enter only an offset for the starting address, the D command 

assumes the segment contained in the DS register. If you specify an 
ending address, enter it with only an offset value. 

For example: 

D cs:100 IOC 

A 40-column display format might look like this: 

04BA:0100 42 45 52 54 41 20 54 00 
BERTA T. 

04BA:0108 20 42 4F 52 47 
BORG 
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E (Enter) Command 


Purpose 

• Replaces the contents of one or more bytes, starting at the specified 
address, with the values contained in the list (see Option 1). 

• Displays and allows modification of bytes in a sequential manner (see 
Option 2). 

Format 

E address [list] 


Parameters 

address Any of the following formats: 

• A segment register plus an offset, such as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment is used. 

list A string of byte values. If you include a character string, 

enclese the characters in single or double quotation marks. To 
specify a quotation mark as a character within the string when it 
is also used to delimit the string, type it twice. 

"These ""quotes"" are correct." 

'This one" s okay, too.' 

Comments 

If you enter only an offset for the address, the E command assumes the 
segment contained in the DS register. 

The Enter command has two format options. 

Option 1 

Use this option to place the list in memory beginning at the specified 
address. 

E address list 

For example: 

E ds:100 F3 "xyz" 8D 
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Memory locations ds:100 through ds:104 are filled with the 5 bytes specified 
in the list. 

Option 2 

Use this option to display the address and the byte of a location, then the 
system waits for your input. 

For example: 

E address 

Enter a 1- or 2-character hexadecimal value to replace the contents of the 
byte; then take any one of the following actions: 

1. Press the space bar to advance to the next address. Its contents are 
displayed. If you want to change the contents take eption 1, above. 

To advance to the next byte without changing the current byte, press the 
space bar again. 

2. Enter a hyphen to back up to the preceding address. A new line is 
displayed with the preceding address and its contents. If you want to 
change the contents, take option 1, above. 

To back up one mere byte without changing the current byte, enter 
another hyphen. 

3. Press the Enter key to end the Enter command. 

Note: Display lines can have 4 or 8 bytes of data, depending en whether the 
system display format is 40- or 80-column. Spacing beyond an 8-byte 
boundary causes a new display line, with the beginning address, to be 
started. 

For example: 

E cs:100 

might cause this display: 

04BA:0100 EB._ 

Te change the contents of 04BA:0100 from hex EB to hex 41, enter 41. 
04BA:0100 EB.41_ 

To see the contents of the next three locatiens, press the space bar three 
times. The screen might look like this: 

04BA:0100 EB.41 10. 00. BC. 
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To change the contents of the current location (04BA:0103) from hex BC to 
hex 42, enter 42. 

04BA:0100 EB.41 10. 00. BC.42_ 

Now, suppose you want to back up and change the hex 10 to hex 6F. This is 
what the screen looks like after entering two hyphens and the replacement 
byte: 

04BA:0100 EB.41 10.00. BC.42- 

04BA:0102 00.- 
04BA:0101 10.6F_ 

Press the Enter key to end the Enter command. The hyphen prompt will 
appear. 


F (Fill) Command 
Purpose 

Fills the memory locations In the range with the values In the list. 


Format 

F range list 


Parameters 

range Either of these two formats: 

• An address followed by an offset, such as CS:100 110 

• An address followed by L value, where value Is the number 
of hexadecimal bytes to be processed. For example, CS:100 
L 10. 

The limit for range Is hexadecimal 10000 or decimal 64K bytes. 
To specify a range of 64K bytes within 4 hexadecimal 
characters, enter 0000 or 0 for value. 

list A string of byte values. If you Include a character string, 

enclose the characters In single or double quotation marks. To 
specify a quotation mark as a character within the string when it 
is also used to delimit the string, type It twice. 

"These ""quotes"" are correct." 

'This one" s okay, too.' 
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Comments 


If the list contains fewer bytes than the address range, the list is used 
repeatedly until all the designated memory locations are filled. 

If the list contains more bytes than the address range, the extra list items are 
ignored. 

Note: If you enter only an offset for the starting address of the range, the Fill 
command assumes the segment contained in the DS register. 


Examples 

F 4BA:100 L 5 F3 "XYZ" 8D 

Memory locations 04BA:100 through 04BA:104 are filled with the 5 bytes 
specified. Remember that the ASCII values of the list charaoters are stored. 
Thus, locations 100-104 will contain F3 58 59 5A 8D. 


G (Go) Command 
Purpose 

Executes the program you are debugging. 

Stops the execution when the instruction at a speoified address is reached 
(breakpoint), and displays the registers, flags, and the next instruction to be 
exeouted. 

Format 

G [ = address] [address [ac/c/ress...]] 


Parameters 

address Any of the following formats: 

• A segment register plus an offset, suoh as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment is used. 
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Comments 


Program execution begins with the current instruction, whose address is 
determined by the centents of the CS and IP registers, uniess overridden by 
the ^address parameter (the = must be entered). If =address is specified, 
program execution begins with CS:=address. 

The Go command has two format options. 

Option 1 

Use this option to execute the pregram you are debugging without 
breakpoints. For exampie: 

G [=address] 

This option is usefui when testing program execution with different 
parameters each time. (Refer te the Name cemmand.) Be certain the CS:IP 
vaiues are set properiy befere issuing the G cemmand, if not using 
= address. 

Option 2 

This option performs the same function as Option 1 but, in addition, aiiows 
breakpoints to be set at the specified addresses. For exampie: 

G [=address] address 
[address. . .] 

This method causes execution to stop at a specified location so the system 
or program environment can be examined. 

You can specify up to ten breakpeints in any order. Yeu may wish te take 
advantage of this if your program has many paths, and you want to stop the 
execution no matter which path the program takes. 

The DEBUG program repiaces the instructien codes at the breakpoint 
addresses with an interrupt code (hex CC). if any one breakpoint is reached 
during execution, the execution is stopped, the registers and fiags are 
dispiayed, and aii the breakpoint addresses are restored to their originai 
instruction codes. If no breakpoint is reached, the instructions are not 
restored. 
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Notes: 


1. Once a program has reached completion (DEBUG has displayed the 
“Program terminated normally” message), you must reload the program 
before it can be executed again. 

2. Make sure that the address parameters refer to locations that contain 
valid 8086/8088 instruction codes. If you specify an address that does not 
contain valid instruction in the first byte, unpredictable results occur. 

3. The stack pointer must be valid and have 6 bytes available for the Go 
command, otherwise, unpredictable results occur. 

4. If only an offset is entered for a breakpoint, the G command assumes the 
segment contained in the CS register. 

5. Do not set breakpoints at instructions in read-only memory (ROM BIOS 
or ROM BASIC). 

For example: 

G 102 lEF 208 

Be careful not to set a breakpoint between a segment override indication 
(such as ES; alone on a line), and the instruction that the override qualifies. 

Execution begins with the current instruction, whose address is the current 
values of CS:IP. The ^address parameter was not used. 

Three breakpoints are specified; assume that the second is reached. 
Execution stops before the instruction at location CS:1EF is executed, the 
original instruction codes are restored, all three breakpoints are removed, 
the display occurs, and the Go command ends. 

Refer to the Register command for a description of the display. 


H (Hexarithmetic) Command 
Purpose 

Adds the two hexadecimal values, then subtracts the second from the first. 
Displays the sum and difference on one line. 
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Format 


H value value 


Examples 

H OF 8 
0017 0007 

The hexadecimal sum of OOOF and 0008 is 0017, and their difference is 0007. 

I (Input) Command 
Purpose 

Inputs and displays (in hexadecimal) 1 byte from the specified port. 

Format 

I portaddress 

Parameters 

portaddress A 1-4 character hexadecimal value specifying an 8- or 16-bit 
port address. 

Examples 

I 2F8 
6B 

The single hexadecimal byte read from port 02F8 is displayed (6B). 

L (Load) Command 
Purpose 

Loads a file or absolute disk sectors into memory. 
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Format 

L [address[clrive sector sector]] 

Parameters 

address Any of the following formats: 

• A segment register plus an offset, such as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment is used. 

drive A decimal number that indicates a particular drive. For 

example, drive A is 0, drive B is 1, and so on. 

sector 1-3 character hexadecimal values that specify the starting 

relative sector number and the number of sectors to be loaded 
or written. 

Note: Relative sector numbers are obtained by counting the 
sectors on the disk surface. The first sector on the disk 
is at track 0, sector 1, head 0, and is relative sector 0. 

The numbering continues for each sector on that track 
and head, then continues with the first sector on the next 
head of the same track. When all sectors on all heads of 
the track have been counted, numbering continues with 
the first sector on head 0 of the next track. 

Comments 

The maximum number of sectors that can be loaded with a single Load 
command is hex 80. A sector contains 512 bytes. 

Note: DEBUG displays a message if a disk read error occurs. You can retry 
the read operation by pressing the F3 key to re-display the Load 
command. Then press the Enter key. 

The Load command has two format options. 

Option 1 

Use this option to load data from the disk specified by drive and place the 
data in memory beginning at the specified address. For example: 

L address drive sector sector 

The data is read from the specified starting relative sector (first sector) and 
continues until the requested number of sectors is read (second sector). 
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Note: If you only enter an offset for the beginning address, the L command 
assumes the segment contained in the CS register. 

For exampie, to ioad data, you might enter: 

L DS:100 1 OF 6D 

The data is ioaded from the diskette in drive B and piaced in memory 
beginning at DS:100. Consecutive sectors of data are transferred, 6DH (109), 
starting with reiative sector hex OF (15) (the 16th sector on the diskette). 

Note: Option 1 cannot be used if the drive specified is a network drive. 

Option 2 

When issued without parameters, or with oniy the address parameter, use 
this option to ioad the fiie whose fiie specification is at CS:80. For exampie: 

L 


or 

L address 

This condition is met by specifying the fiie name when starting the DEBUG 
program, or by using the Name command. 

Note: If DEBUG was started with a fiie specification and subsequent Name 
commands were used, you may need to enter a new Name command 
for the proper fiie specification before issuing the Load command. 

The fiie is ioaded into memory beginning at CS:100 (or the iocation specified 
by address), and is read from the drive specified in the fiie specification, or 
from the defauit drive, if none was specified. Note that fiies with extensions 
of .COM or .EXE are aiways ioaded at CS:100. If you specified an address, it 
is ignored. 

The BX and CX registers are set to the number of bytes read; however, if the 
fiie being ioaded has an extension of .EXE, the BX and CX registers are set 
to the actuai program size. The fiie may be ioaded at the high end of 
memory. Refer to “The DEBUG Work Space” on page 48 for the conditions 
that are in effect when .EXE or .HEX fiies are ioaded. 

For exampie: 

DEBUG 
-N myprog 
-L 
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The file named myprog is loaded from the default directory and placed in 
memory beginning at location CS:0100. 


M (Move) Command 
Purpose 

Moves the contents of the memory locations specified by range to the 
locations beginning at the address specified. 

Format 

M range address 


Parameters 

range Either of these two formats: 

• An address followed by an offset, such as CS:100 110. 

• An address followed by L value, where value is the number 
of hexadecimal bytes to be processed. For example, CS:100 
L 10. 

The limit for range is hexadecimal 10000 or decimal 64KB. To 
specify a range of 64KB within 4 hexadecimal characters, enter 
0000 or 0 for value. 

address Any of the following formats: 

• A segment register plus an offset, such as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment is used. 


Comments 

Overlapping moves are always performed without loss of data during the 
transfer. (The source and destination areas share some of the same 
memory locations.) 

The data in the source area remains unchanged unless overwritten by the 
move. 
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Notes: 

1. If you enter only an offset for the beginning address of the range, the M 
command assumes the segment contained in the DS register, if you 
specify an ending address for the range, enter it with oniy an offset 
vaiue. 

2. If you enter only an offset for the address of the destination area, the M 
command assumes the segment contained in the DS register. 


Examples 

M CS:100 LIO 500 

The 17 bytes of data from CS:100 through CS:110 are moved to the area of 
memory beginning at DS:500. 


N (Name) Command 
Purpose 

• Formats file control blocks for the first two file specifications, at CS:5C 
and CS:6C. (Starting DEBUG with a file specification also formats a file 
control block at CS:5C.) 

The file control blocks are set up for the Load and Write commands and 
to supply required file names for the program being debugged. 

• All file specifications and other parameters, including delimiters, are 
placed exactly as entered in a parameter save area at CS:81, with CS:80 
containing the number of characters entered. Register AX is set to 
indicate the validity of the drive specifiers entered with the first two file 
specifications. 

Format 

N [d:][pa\h]filename[.ext] 


Comments 

If you start the DEBUG program without a file specification, you must use the 
Name command before a file can be loaded with the L command. 
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Examples 


DEBUG 
-N myprog 
-L 


To define file specifications or other parameters required by the program 
being debugged, enter: 

DEBUG myprog 
-N filel file2 


In this example, DEBUG loads the file myprog at CS:100, and leaves the file 
control block at CS:5C formatted with the same file specification. Then, the 
Name command formats file control blocks for filel and file2 at CS:5C and 
CS:6C, respectively. The file control block for myprog Is overwritten. The 
parameter area at CS:81 contains all characters entered after the N, 
Including all delimiters, and CS:80 contains the count of those characters 
(hex DC). 


O (Output) Command 
Purpose 

Sends the byte to the specified output port. 


Format 

O portaddress byte 


Parameters 

portaddress A 1-4 character hexadecimal value specifying an 8- or 16-blt 
port address. 


Examples 

To send the byte value 4F to output port 2F8, enter: 
0 2F8 4F 
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P (Proceed) Command 


Purpose 

Causes the execution of a subroutine caii, a ioop instruction, an interrupt, or 
a repeat string instruction to stop at the next instruction. 

Format 

P[=aclclress][vaiue] 


Parameters 

address Any of the foilowing formats: 

• A segment register pius an offset, such as CS:0100. 

• A segment address pius an offset, such as 4BA:0100. 

• An offset oniy, such as 100. In this case, the defauit 
segment is used. 

value A 1-4 character hexadecimai vaiue, specifying the number of 

instructions to execute. 

Comments 

When at a subroutine cail, a ioop instruction, an interrupt, or a repeat string 
instruction, issue the Proceed command to execute the instruction (perform 
the entire function), and return controi at the next instruction. The Proceed 
command has the same syntax as the Trace command. Specifying PO is the 
same as specifying TO. 


Examples 

If the following instructions are executed: 


0100 

CALL 

1000 

0103 

JC 

2000 

1000 

XOR 

AX, AX 

IXXX 

RET 



And if CS:IP was pointing to the CALL 1000 instruction, typing P causes the 
execution of the subroutine and returns control to DEBUG at the JC 
instruction. 
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Q (Quit) Command 


Purpose 

Ends the DEBUG program. 


Format 

Q 


Comments 

The file that you are working on in memory is not saved by the Quit 
oommand. You must use the Write command to save the file. 

DEBUG returns to the command processor which then issues the normal 
command prompt. 


Examples 


-Q 

A> 


R (Register) Command 
Purpose 

The Register command has the following three functions: 

• Displays the hexadecimal contents of a single register with the option of 
changing those contents 

• Displays the hexadecimal contents of all the registers, plus the 
alphabetic flag settings, and the next instruction to be executed 

• Displays the eight 2-letter alphabetic flag settings with the option of 
changing any or all of them. 

Format 

R [registername] 
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Parameters 


registername The valid names are: 


AX 

SP 

CS 

IP 

BX 

BP 

DS 

F 

CX 

SI 

ES 


DX 

DI 

SS 



IP refers to the Instruction pointer, and F refers to the flags 
register. 


Comments 

When the DEBUG program starts, the registers and flags are set to oertain 
values for the program being debugged. (Refer to “The DEBUG Work Space” 
on page 48.) 

Display a Single Register 

To display the contents of a single register, enter the register name: 

R AX 

The system might respond with: 

AX F1E4 


Now you oan take one of two actions: press the Enter key to leave the 
contents unchanged, or change the contents of the AX register by entering a 
1-4 character hexadecimal value, such as hex FEE. 

AX F1E4 
:FFF_ 

Now, pressing the Enter key changes the contents of the AX register to hex 
OFFF. 

Display All Registers and Flags 

To display the contents of all registers and flags and the next Instruotlon to 
be executed, type: 

R 

The system responds: 

AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000 
DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011A NV UP El PL NZ NA PO NC 
3D5B:011A CD21 INT 21 
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The first four lines display the hexadecimal contents of the registers and the 
eight alphabetic flag settings. The last line indicates the location of the next 
instruction to be executed and its hexadecimal and unassembled formats. 
This is the instruction pointed to by CS:IP. 

A system with an 80-column display shows: 

1st line - 8 registers 

2nd line - 5 registers and 8 flag settings 
3rd line - next instruction information 

A system with a 40-column display shows: 

1st line - 4 registers 

2nd line - 4 registers 

3rd line - 4 registers 

4th line - 1 register and 8 flag settings 

5th line - next instruction information 

Display All Flags 

There are eight flags, each with two-letter codes to indicate either a set 
condition or a clear condition. The flags appear in displays in the order 
shown in the following table: 


Flag Name 

Set 

Clear 

Overflow (yes/no) 

OV 

NV 

Direction (decrease/increase) 

DN 

UP 

interrupt (enabie/disabie) 

El 

Dl 

Sign (negative/positive) 

NG 

PL 

Zero (yes/no) 

ZR 

NZ 

Auxiiiary carry (yes/no) 

AC 

NA 

Parity (even/odd) 

PE 

PO 

Carry (yes/no) 

CY 

NC 


To display all flags, enter: 

R F 

If all the flags are in a set condition, the respcnse is: 

OV DN El NG ZR AC PE CY - _ 

Now you can either press the Enter key to leave the settings unchanged or 
change any or all of the settings. 
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To change a flag, just enter its opposite code. The opposite codes can be 
entered in any order with or without intervening spaces. For example, to 
change the first, third, fifth, and seventh flags, enter: 

OV DN El NG ZR AC PE CY - PONZDINV 

The changes in this example are entered in reverse order. 

Press the Enter key and the flags are modified as specified, the prompt 
appears, and you can enter the next command. 

If you want to see if the new codes are in effect, enter: 

R F 

The response is: 

NV DN DI NG NZ AC PO CY - _ 

The first, third, fifth, and seventh flags are changed as requested. The 
second, fourth, sixth, and eighth flags are unchanged. A single flag can be 
changed only once for each R F command. 


S (Search) Command 
Purpose 

Searches the range for the characterjs) in the list. 


Format 

S range list 

range Either of these two formats: 

• An address followed by an offset, such as CS:100 110. 

• An address followed by L value, where value is the number 
of hexadecimal bytes to be processed. For example, CS:100 
L 10. 

The limit for range is hexadecimal 10000 or decimal 64KB. To 
specify a range of 64KB within 4 hexadecimal characters, enter 
0000 or 0 for value. 

list A string of byte values. If you include a character string, 

enclose the characters in single or double quotation marks. To 
specify a quotation mark as a character within the string when it 
is also used to delimit the string, type it twice. 
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"These ""quotes"" are correct." 
'This one" s okay, too.' 


Comments 

All matches are Indicated by displaying the addresses where matches are 
found. 


A display of the prompt without an address means that no match was found. 

Note: If you enter only an offset for the starting address of the range, the S 
command assumes the segment contained In the DS register. 


Examples 

If you want to search the range of addresses from CS:100 through CS:110 for 
hex 41 , type: 

S CS:100 no 41 

If two matches are found the response might be: 

04BA:0104 

04BA:010D 

If you want to search the same range of addresses for a match with the 
4-byte list (41 "AB" E), enter: 

S CS:100 L 11 41 "AB" E 

The starting addresses of all matches are listed. If no match Is found, no 
address Is displayed. 


T (Trace) Command 
Purpose 

Executes one or more Instructions starting with the Instruction at CS:IP, or at 
= address, if it is specified. The = must be entered. One instruction is 
assumed, but you can specify more than one with value. This command 
displays the contents of all registers and flags after each Instruction 
executes. For a description of the display format, refer to the Register 
command. 
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Format 


T [ = address] [ value] 


Parameters 

address Any of the following formats: 

• A segment register plus an offset, such as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment is used. 

value A 1-4 character hexadecimal value, specifying the number of 

instructions to execute. 

Comments 

The display caused by the Trace command continues until value instructions 
are executed. Therefore, when tracing multiple instructions, remember you 
can suspend the scrolling at any time by pressing the Ctrl and the NumLock 
keys together, or the Pause key. Resume scrolling by entering any other 
character. 

Notes: 

1. The Trace command disables all hardware interrupts before executing 
the user instruction, and then re-enables the interrupts when the trap 
interrupt occurs following the execution of the instruction. 

2. TRACE should not be used with any steps that change the contents of the 
8259 interrupt mask (ports 20 and 21). 

3. If you trace an INT3 instruction, the breakpoint is set at the INT3 location. 

Examples 

T 

If the IP register contains 01 1A, and that location contains B40E (MOV 
AH, OEM), this may be displayed: 

AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C 01=0000 
DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011C NV UP El PL NZ NA PO NC 
3D5B:011C CD21 INT 21 

This displays the results after {he instruction at 011 A is executed, and 
indicates the next instruction to be executed is the INT 21 at location 
04BA:011C. 

T 10 
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Sixteen instructions are executed (starting at CS:IP). The contents of aii 
registers and fiags are dispiayed after each instruction. The dispiay stops 
after the 16th instruction has been executed. Dispiays may scroii off the 
screen uniess you suspend the dispiay by simuitaneousiy pressing the Ctri 
and NumLock keys, or the Pause key. 


U (Unassemble) Command 
Purpose 

Unassembies instructions (that is, transiates the contents of memory into 
assembier-iike statements) and dispiays their addresses and hexadecimai 
vaiues, together with assembier-iike statements. For exampie, a dispiay 
might iook iike this: 

04BA:0100 206472 AND [SI+72],AH 

04BA:0103 FC CLD 

04BA:0104 7665 JBE 016B 

Format 

U [ac/cfress] 
or 

U [range] 

Parameters 

address Any of the foiiowing formats: 

• A segment register pius an offset, such as CS:0100. 

• A segment address pius an offset, such as 4BA:0100. 

• An offset oniy, such as 100. In this case, the defauit 
segment is used. 

range Either of these two formats: 

• An address foiiowed by an offset, such as CS:100 110. 

• An address foiiowed by L value, where value is the number 
of hexadecimai bytes to be processed. For exampie, CS:100 
L 10. 

The iimit for range is hexadecimai 10000 or decimai 64KB. To 
specify a range of 64KB within 4 hexadecimai characters, enter 
0000 or 0 for value. 
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Comments 


The number of bytes to be unassembled depends on your system display 
format (40 or 80 columns), and which option you use with the Unassemble 
command. 

Notes: 

1. In all cases, the number of bytes unassembled and displayed may be 
slightly more than either the amount requested or the default amount. 

This happens because the length of the instructions vary. Therefore, 
unassembling the last instruction may result in more bytes than 
expected. 

2. Make sure that the address parameters refer to locations containing valid 
8086/8088 instruction codes. If you specify an address that does not 
contain the first byte of a valid instruction, the display will be incorrect. 

3. If you enter only an offset for the starting address, the U command 
assumes the segment contained in the CS register. 

The Unassemble command has the following two format options: 

Option 1 

Use this option to either unassemble instructions without specifying an 
address, or to unassemble instructions beginning with a specified address. 
For example: 

U 


or 

U address 

Sixteen bytes are unassembled with a 40-column display. Thirty-two bytes 
are unassembled in 80-column mode. 

Instructions are unassembled beginning with the specified address. 

If you do not specify an address, the U command assumes the starting 
address is the location following the last instruction unassembled by a 
previous U command. Thus, it is possible to unassemble consecutive 
locations, producing continuous unassembled displays, by entering 
consecutive U commands without parameters. 

If no previous U command is entered, the location is offset hex 0100 into the 
segment originally initialized in the segment registers by DEBUG. 
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Option 2 


Use this option to unassembie instructions in a specified address range. For 
exampie: 

U range 

Ail instructions in the specified address range are unassembied, regardiess 
of the system dispiay format. 

Note: If you specify an ending address, enter it with oniy an offset vaiue. 

For exampie: 

U 04ba:0100 108 

The dispiay response may be: 

04BA:0100 206472 AND [SI+72],AH 

04BA:0103 FC OLD 

04BA:0104 7665 JBE 016B 

04BA:0106 207370 AND [BP+DI+70] ,DH 

The same dispiay appears if you enter: 

U 04BA:100 L 7 

or 

U 04BA:100 L 8 
or 

U 04BA:100 L 9 


W (Write) Command 


Purpose 

Writes the data being debugged to disk. 

Format 


W [address [drive sector sector]] 
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Parameters 

address Any of the following formats: 

• A segment register plus an offset, such as CS:0100. 

• A segment address plus an offset, such as 4BA:0100. 

• An offset only, such as 100. In this case, the default 
segment is used. 

drive A decimal number that indicates a particular drive. For 

example, drive A is 0, drive B is 1, and so on. 

sector 1-3 character hexadecimal values that specify the starting 

relative sector number and the number of sectors to be loaded 
or written. 

Note: Relative sector numbers are obtained by counting the 
sectors on the disk surface. The first sector on the disk 
is at track 0, sector 1, head 0, and is relative sector 0. 

The numbering continues for each sector on that track 
and head, then continues with the first sector on the next 
head of the same track. When all sectors on all heads of 
the track have been counted, numbering continues with 
the first sector on head 0 of the next track. 

Comments 

No more than hex 80 sectors can be written with a single Write command. A 
sector contains 512 bytes. 

DEBUG displays a message if a disk write error occurs. You can retry the 
write operation by pressing the F3 key to re-display the Write command, then 
press the Enter key. 

The Write command has two format options. 

Option 1 

Use this option to write data to disk beginning at a specified address. For 
example: 

W address drive sector sector 

The data beginning at the specified address is written to the disk in the 
indicated drive. The data is written starting at the specified starting relative 
sector (first sector) and continues until the requested number of sectors are 
filled (second sector). 
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Notes: 


1. Be extremely careful when you write data to absolute sectors because an 
erroneous sector specification destroys whatever was on the disk at that 
location. 

2. If only an offset Is entered for the beginning address, the W command 
assumes the segment Is contained In the CS register. 

3. Remember, the starting sector and the sector count are both specified in 
hexadecimal. 

4. Option 1 cannot be used if the specified drive is a network drive. 

For example: 

W IFD 1 100 A 

The data beginning at CS:01FD is written to the diskette in drive B, starting at 

relative sector hex 100 (256) and continuing for hex OA (10) sectors. 

Option 2 

This option permits you to use the WRITE command without specifying 

parameters or specifying only the address parameter. For example: 

W 


or 

W address 

When issued as shown above, the Write command writes the file (whose file 
specification is at CS:80) to disk. 

This condition is met by specifying the file when starting the DEBUG 
program, or by using the Name command. 

Note: If DEBUG was started with a file specification and subsequent Name 
commands were used, you may need to enter a new Name command 
for the proper file specification before Issuing the Write command. 

In addition, the BX and CX registers must be set to the number of bytes to be 
written. They may have been set properly by the DEBUG or Load 
commands, but were changed by a Go or Trace command. You must be 
certain the BX and CX registers contain the correct values. 

The file beginning at CS:100, or at the location specified by address, is 
written to the diskette in the drive included in the file specification or the 
default drive If no drive was specified. 
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The debugged file is written over the eriginal file that was loaded into 
memory, or into a new file if the file name in the FCB didn't previously exist. 

Note: An error message is issued if you try to write a file with an extension 
of .EXE or .HEX. These files are written in a specific format that 
DEBUG cannot support. 

If you find it necessary to modify a file with an extension of .EXE or .HEX, and 
the exact locaticns to be modified are known, use the following procedure: 

1. RENAME the file to an extension other than .EXE or .HEX. 

2. Load the file into memory using the DEBUG or Load command. 

3. Modify the file as needed in memory, but do not try to execute it with the 
Go or Trace commands. Unpredictable results would occur. 

4. Write the file back using the Write command. 

5. RENAME the file to its correct name. 


XA (EMS Allocate) Command 
Purpose 

Allocates a specified number of expanded memory pages to a handle. 


Format 

XA count 


Comments 

The count indicates the number cf 16K pages to allocate. If the amount of 
expanded memory identified by count is available, a message is displayed, 
indicating that a handle has been created. The XS (EMS Status) command 
can be used to display the number of expanded memory pages that are 
available. 


Examples 

To allocate two EMS pages, enter: 

XA 2 

If twc pages of memory are available, a message like this is displayed: 
Handle created = OOOE 
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XD (EMS Deallocate) Command 


Purpose 

Deallocates a handle. 


Format 

XD handle 


Comments 

The handle Identifies the number of the handle to be deallocated. If the 
number Is valid, a message Is displayed, Indicating the handle has been 
deallocated. The XS (EMS Status) command can be used to display the 
handles currently being used. 


Examples 

To deallocate a handle when you have only one allocated, you can enter: 
XD OOOE 

If the handle deallocation is successful, you receive a message like this: 
Handle OOOE deallocated. 


XM (EMS Map) Command 
Purpose 

Maps an EMS logical page to an EMS physical page from an EMS handle. 


Format 

XM Ipage ppage handle 


Comments 

The Ipage specifies the number of the handle's logical page that Is to be 
mapped. The ppage Is the number of the physical page to be mapped to. 
The handle is the EMS allocated label used to reference a group of logical 
pages. If syntax Items are valid, a message is displayed Indicating that the 
logical page has been mapped to the physical page. 
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Examples 


To map a logical page to a physical page using handle 0001, you can enter: 
XM 1 0 1 

If the mapping is successful, ycu receive this message: 

Logical page 01 mapped to physical page 00. 


XS (EMS Status) Command 
Purpose 

Displays the status of expanded memory. 

Format 

XS 

Comments 

The follcwing expanded memory information is displayed: 
Handle %1 has %2 pages allocated 

Physical page %1 = Frame segment %2 

%1 of a total %2 EMS pages have been allocated 
%1 of a total %2 EMS handles have been allocated 


Examples 

A line is displayed for each handle allocated with its asscciated logical page 
count. 
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DEBUG Error Messages 

The following error messages are produced by the DEBUG utility: 

Access denied 


Disk error reading drive %1 

Disk error writing drive %1 

EMS hardware/software faiiure 

EMS not instailed 

A Error 

Error in EXE or HEX fiie 

EXE and HEX files cannot be written 

EXEC faiiure 

Fiie creation error 

Fiie not found 

Free pages exceeded 

Handie not found 

Incorrect DOS version 


The result of attempting to Write (W) to 
a read-only file. 

An Invalid parameter was entered on 
the Load (L) command or an error 
occurred on Issuing the Load (L) 
command. 

An invalid parameter was entered on 
the Write (W) command or an error 
occurred on issuing the Write (W) 
command. 

The result cf an EMS command. Tells 
the user EMS is not functioning 
properly. 

The result cf an EMS command. Tells 
user EMS Is not Installed. 

Points to the offending eperand In an 
error condition. 

The EXE or HEX file are In error. 

A file in EXE or HEX format cannot be 
written to a disk. 

The execution of the requested file 
failed. 

The result of attempting to Write (W) to 
a system or hidden file. 

Issued from the Load (L) command 
when a file Is not found for loading. 

The result cf an EMS command. Tells 
the user that the request has exceeded 
the amount of free EMS pages 
available. 

The result cf an EMS command. Tells 
the user an EMS handle was not found. 

Incorrect version of DEBUG for the DOS 
version running. 
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Insufficient memory 
Insufficient space on disk 
Invaiid drive specification 

Logical Page out of range 

Missing or invalid EMS parameter 

No free handies 

Parameter error 

Physicai Page out of range 

Program terminated normaily 
Total pages exceeded 


Not enough memory to Load (L) the 
specified fiie. 

Out of disk space for a Write (W) 
command. 

The drive referenced by the Name (N) 
and Load (L) command is invaiid; that 
is, it does not exist. 

The resuit of an EMS command. Teiis 
the user that the iogicai page requested 
is not in the range of possibie pages. 

The resuit of an EMS command. Teiis 
the user a missing or invaiid parameter 
was entered. 

The resuit of an EMS command. Teiis 
the user that there are no more EMS 
handies avaiiabie for ailocation. 

The resuit of an EMS command. Teiis 
the user that an EMS parameter is in 
error. 

The resuit of an EMS command. Teiis 
the user that the physicai page 
requested is not in the range of 
possibie pages. 

An Interrupt 20H has been encountered, 
signaiiing program termination. 

The resuit of an EMS command. Teiis 
the user that the totai EMS pages have 
been exceeded. 


Write (W) error, no destination defined Attempt to Write (W) to a fiie that has 

not yet been Named (N). 

Write protect error writing drive %1 A Write (W) to a write-protected disk 

caused an error. 

Writing %1 bytes Reports the number of bytes written to 

a fiie when the Write (W) command is 
issued. 
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Chapter 8. Writing an Installable Device Driver 


This chapter provides guide and system architecture information to support 
successfui creation of an instaiiabie device driver. 


Types of Device Drivers 

A device driver is a memory image fiie or an .EXE fiie that contains the code 
needed to impiement a device. DOS aiiows two types of device drivers to be 
instaiied: 

• Character device drivers 

• Biock device drivers. 

Character Device Drivers 

Character device drivers perform character i/0 in a seriai manner and have 
names such as CON, AUX, CLOCK$. You can open handies or FCBs to 
perform input and output to character devices. Because character device 
drivers have oniy one name, they support oniy one device. 

Biock Device Drivers 

Biock device drivers are the hard disk or diskette drives on the system. 

They perform random i/0 in pieces caiied biocks, which are usuaiiy the 
physicai sector size of the disk. Biock devices are not named as character 
devices are and you cannot open them, instead they are mapped using the 
drive ietters such as A, B, and C. 

A singie biock device driver can be responsibie for one or more disk or 
diskette drives. For exampie, the first biock device driver in the device chain 
may define four units such as A, B, C, and D. The second device driver may 
define three units: E, F, and G. The iimit is 26 devices with the ietters A 
through Z assigned to drives. The position of the driver in the chain 
determines the way in which the drive units and drive ietters correspond. 


How PC DOS 7 Installs Device Drivers 

PC DOS 7 instaiis device drivers at startup time by reading and processing 
the DEViCE command in CONFiG.SYS. For exampie, if you have written a 
device driver caiied DRIVER1, include the following command in 
CONFIG.SYS: 

devi ce=dri verl 


© Copyright IBM Corp. 1995 
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In PC DOS 7 a new command DYNALOAD has been added to allow you to 
dynamically load device drivers from the command line. The following is an 
example of this: 

C:>DYNALOAD ANSI. SYS 

The PC DOS 7 device interface links device drivers together in a chain, 
permitting you to add device drivers for optional devices. 

Each device must be initialized. The device driver's initialization interrupt 
routine is called once when the device is installed. The initialization routine 
returns the location in memory of the ending address of the device driver. 
After setting the ending address field, a character device driver sets the 
status word and returns. 

PC DOS 7 processes installed character device drivers before handling 
default devices. To have PC DOS 7 install a new CON device (for example, 
in the device driver header's Name/Unit field) name the device CON and set 
the standard input device and standard output device bits in the attribute 
field. Because PC DOS 7 installs drivers anywhere in memory, care must be 
taken in any references to locations not in the segment. Your driver will not 
always be loaded at the same memory location each time. 

Block devices are installed in the same manner as character devices, above. 
Block devices return additional information such as the number of units. 

This number identifies the devices' logical names. For example, if the 
current maximum logical device letter is F at the time of the install call, and 
the block device driver initialization routine returns three logical units, the 
logical names of the devices are G, FI, and I. The mapping is determined by 
the position of the driver in the device list and the number of units associated 
with the device. The number of units returned by INIT overrides the value in 
the name/unit field of the device header. 

A block device also returns a pointer to a BIOS parameter block (BPB) array. 
This is a pointer to an array of n word pointers, where n is the number of 
units defined. If all the units are the same, the array is able to point to the 
same BIOS parameter block, thus saving space. The array must be 
protected below the ending address pointer set by the return. 

The BPB contains information pertinent to the devices such as the sector 
size and the number of sectors per allocation unit. The sector size in the 
BPB cannot be greater than the maximum allowed size set by PC DOS 7 
initialization. 

A block device returns the media descriptor byte passed to devices to report 
which parameters PC DOS 7 is using for a particular drive unit. 
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The Basic Parts of a Device Driver 


A device driver is a memory image file or an .EXE file containing the code 
needed to implement a device. All PC DOS 7 installable device drivers have 
these things in common: 

• A device driver header, which identifies the device to PC DOS 7 and 
defines the strategy and interrupt entry points. Since a device driver is 
simply loaded and does not use a program segment prefix, the device 
header must be located at physical location 0 of the device driver (ORG 0 
or no ORG statement). 

• A strategy routine, which saves a pointer to the Request Header. 

• The interrupt routines, which perform the requested operation. 

The Device Driver Header 

A device driver requires a device header containing the following: 


Field 


Length 

Pointer to 

next device header 

DWORD 

Attribute 


WORD 

Pointer to 

device strategy routine 

WORD 

Pointer to 

device interrupt routine 

WORD 

Name/unit tield 

8 BYTES 


Pointer to Next Device Header 

The device driver header is a pointer to the device header of the next device 
driver. It Is a doubleword field set by PC DOS 7 at the time the device driver 
Is loaded. The first word is an offset and the second word is the segment. 

If you are loading only one device driver, set the device header field to -1 
before loading the device. If you are loading more than one device driver, 
set the first word of the device header field to the offset of the next device 
driver's header. Set the device header field of the last device driver to -1. 

Attribute Field 

The attribute field Identifies the device te PC DOS 7. 
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Bit 15 

Bit 15 identifies whether the device is a bleck device or a character device. 

If bit 15 is set to 0, this indicates a block device. Setting bit 15 to 1 indicates 
a character device. Note how the setting of bit 15 affects the interpretation of 
the setting of the bits below. 

Bit 14 

Bit 14, for both character and block devices, tells PC DOS 7 whether the 
device driver can handle control strings through lOCtI 44H, AL=2 through 
AL = 5. Set bit 14 to 1 if control strings can be processed. lOCtI subfunctions 
permit the device driver to interpret the information passed to it, such as 
setting a baud rate or changing form lengths, without performing standard 
reads and writes. Set bit 14 to 0 if control strings cannot be processed. PC 
DOS 7 will return an error if an lOCtI is issued to send or receive control 
strings and bit 14 is set to 0. 

Bit 13 

Bit 13 is used for both block and character devices. For block devices, set bit 
13 to 0 if the media is an IBM format. Set bit 13 to 1 if the media is a 
non-IBM format. For character devices, set bit 13 to 0 if the driver supports 
output-until-busy. Set bit 13 to 1 if it does not. 

With the support of output-until-busy, the device driver will send characters 
to the device if the device is ready. If the device is not ready, the device 
driver will immediately return an error. 

Bit 12 

Bit 12 is reserved. 

Bit 11 

Set bit 11 if the device driver can handle removable media. This bit is called 
the open/close removable media bit. 

Bits 10-8 

Bits 10 through 8 are reserved. 

Bit 7 

For DOS 5.0 and later versions, set bit 7 to 1 to indicate that a device driver 
supports Query lOCtl. If this bit is set, the driver can be called with function 
19FI (with a standard Generic lOCtI request packet). 
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Bit 6 

Bit 6 is the generic lOCti bit for both character and biock device drivers. If 
this bit is set to 1, the device driver supports generic lOCtI function calis. 
Setting this bit to 1 aiso indicates support of the Get/Set Logicai Drive 
function for a biock device driver. 

Bits 5 and 4 

Bits 5 and 4 are reserved. 

Bit 3 

Set bit 3 to 1 if the character device is a ciock device; set bit 3 to 0 if it is not. 

Bit 2 

Set bit 2 to 1 if the character device is the NUL device; set bit 2 to 0 if it is 
not. Setting the bit teiis PC DOS 7 whether the NUL device is being used. 

The NUL device cannot be reassigned. 

Bit 1 

If bit 15 is set to 1 for a character device, set bit 1 to 1 to indicate that the 
character device is the current standard output device. If bit 15 is set to 0 for 
a biock device, set bit 1 to 1 to indicate support for 32-bit sector numbers; 
otherwise, 16-bit sector number support is assumed. 

Bit 0 

Set bit 0 to 1 if the character device is the current standard input device; set 
bit 0 to 0 if it is not the current standard input device. 

Pointers to Strategy and Interrupt Routines 

When PC DOS 7 passes a request to a device driver, it caiis the device driver 
twice. These two fieids point to the first and second entry points: the 
strategy routine and the interrupt routine. The fieids are word vaiues, so 
they must be in the same segment as the device header. 

Name/Unit Field 

These 8-byte fieids identify a character device by name or a biock device by 
unit. A character device name is ieft-justified foilowed by spaces, if 
necessary. For biock devices, aithough PC DOS 7 automaticaiiy filis in this 
fieid with the vaiue of number of units returned by INIT caii, you may choose 
to piace the number of units in the first piace. 
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The Strategy Routine 

PC DOS 7 calls a device driver at the strategy routine at first, passing in a 
request packet the information describing what PC DOS 7 wants the device 
driver to do. 

The strategy routine does not perform the request but queues the request or 
saves a pointer to the request packet. 

The Interrupt Routine 

PC DOS 7 calls the device driver's interrupt routine with no parameters 
immediately after the strategy routine returns. An interrupt routine's function 
is to perform the operation based on the queued request, process any data 
in the request packet, and set up information being returned to PC DOS 7. 

It is the responsibility of the device driver to preserve the system state. For 
example, the device driver must save all registers on entry and restore them 
on exit. The stack maintained by PC DOS 7 is used to save all registers. If 
more stack space is needed, it is the device driver's responsibility to allocate 
and maintain an additional stack. 

All calls to device drivers are FAR calls. FAR returns should be executed to 
return to PC DOS 7. 


How PC DOS 7 Passes a Request 

PC DOS 7 passes a pointer in ES:BX to the request packet. The packet 
consists of a request header that contains information common to all 
requests, followed by data pertinent to the request being made. 

The structure of the request header is shown below. 


Field 

Length 

Length of the request header and subsequent data 

BYTE 

Unit code for block devices only 

BYTE 

Command code 

BYTE 

Status 

WORD 

Reserved 

8-BYTE 

Data 

VARIABLE 
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Length Field 

The length field identifies the length of the request header and subsequent 
data in bytes. 

Unit Code Field 

The unit code field identifies the requesting unit in a block device driver. If a 
block device driver has three units defined, for example, the possible values 
for the unit code field are 0, 1, or 2. 

Command Code Field 

The command code identifies the request. See “Responding to Requests” on 
page 92 for a list of command code values and request descriptions. 

Status Field 

The status word field is zero on entry and is set by the driver interrupt 
routine on return. 

Bit 15 

Bit 15 is the error bit. If bit 15 is set to 1, the low order 8 bits of the status 
word (7-0) indicate the error code. 

Bits 14-10 

Bits 14 through 10 are reserved. 

Bit 9 

Bit 9 is the busy bit. As a response to status request call, character device 
drivers can set the busy bit to indicate whether or not a device is ready to 
perform input and output requests. Block device drivers can set the busy bit 
to indicate removable or nonremovable media. See “Character Input and 
Output Status Requests” on page 101 and “Removable Media Request” on 
page 103 for more information about the calls. 

Bit 8 

Bit 8 is the done bit. If set, the operation is complete. The driver sets the 
done bit to 1 when it exits. 

Bits 7-0 

Bits 7 through 0 are the low order 8 bits of the status word. If bit 15 is set, 
bits 7 through 0 contain the error codes. The error codes and errors are: 


Codes 

Meaning 

00 

Write protect violation 

01 

Unknown unit 

02 

Device not ready 
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03 Unknown command 

04 CRC error 

05 Bad drive request structure length 

06 Seek errer 

07 Unknown media 

08 Sector not found 

09 Printer out of paper 

OA Write fault 

OB Read fault 

OC General failure 

OD Reserved 

OE Reserved 

OF Invalid disk change 


Responding to Requests 

Each request packet that is passed to the device driver centains a command 
code value in the request header to tell the driver which function to perform. 
The following table contains the PC DOS 7 device interface command code 
values and the functions to be performed when these values are passed with 
data. Note that some cf these functions are specific to either a block device 
or a character device. 

Following this table are detailed descriptions of request data structures and 
what the interrupt rcutines are expected tc do. Some of these descriptions 
pertain to more than one ccmmand code. 


Command 

Request 

Device 

Code 

Description 

Type 

0 

Initialization 

Both 

1 

Media check 

Block 

2 

Build BPB 

Block 

3 

lOCtI input (called only if bit 14 of attribute is set to 1) 

Both 

4 

Input (read) 

Both 

5 

Nondestructive input no wait 

Character 

6 

Input status 

Character 

7 

Input flush 

Character 

8 

Output (write) 

Both 

9 

Output (write with verify) 

Block 

10 (OAH) 

Output status 

Character 

11 (OBH) 

Output flush 

Character 
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Command 

Code 

Request 

Description 

Device 

Type 

12 (OCH) 

iOCti output (caiied oniy it bit 14 ot attribute is set to 

1) 

Character 

13 (ODH) 

Device open (caiied only If bit 11 of attribute is set to 

1) 

Both 

14 (OEM) 

Device close (called only if bit 11 of attribute is set to 

1) 

Both 

15 (OFH) 

Removable media (called only if bit 11 of attribute is 
set to 1) 

Block 

16 (10H) 

Output until busy character 

Both 

19 (13H) 

Generic IOCti Request (called only if bit 6 of attribute 
is set to 1) 

Block 

23 (17H) 

Get logical device (called only if bit 6 of attribute is 
set to 1) 

Block 

24 (18H) 

Set logical device (called only if bit 6 of attribute is 
set to 1) 

Block 

25 (19H) 

IOCti Ouery (called only if bit 7 of attribute is set to 

1) 

Both 


Initialization Request 

Command Code = 0 


Field 

Length 

Request header 

13 - BYTE 

Number of units (not set by character devices) 

BYTE 

Ending address of resident program code 

DWORD 

Pointer to BPB array (not set by character devices) pointer to remainder 
of arguments 

DWORD 

Drive number 

BYTE 

CONFIG.SYS Error Message control flag 

WORD 


The driver must do the following: 

• Set the number of units (block devices only). 

• Set up the pointer to the BPS array (block devices only). 

• Perform any initialization code (to modems, printers, and others). 

• Set the ending address of the resident program code. 

• Set the status word in the request header. 

To obtain information passed from CONFIG.SYS to a device driver at 
initialization time, the BPB pointer field points to a buffer containing the 
information passed in CONFIG.SYS following the =. This string may end 
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with either a carriage return (ODH) or a linefeed (OAH). This information is 
read-only. Only system calls 01H-0CH and 30H can be Issued by the 
Initialization code of the driver. 

The last byte parameter contains the drive letter for the first unit of a block 
driver. For example, 0=A, 1=B and so forth. 

If an Initialization routine determines that it cannot set up the device and 
wants to terminate without using any memory, use the following procedure: 

• Set the number of units to 0. 

• Set the ending address offset to 0. 

• Set the ending address segment to the code segment (CS). 

For DOS 5.0 support; when loading device drivers into UMBs (Upper Memory 
Blocks), PC DOS 7 sets the maximum address that Is available to the device 
driver In the INIT request packet. This Is stored In the ending address field 
before the device's INIT function is called. The value is the normalized 
address of the top of the memory block that Is allocated to the driver. This Is 
done before devices complete Initialization so memory requirements can be 
checked against the amount of space available. If there is not enough space 
for a device's code and data requirements, they will fail to load. 

Block device drivers must account for the space needed for a Disk 
Parameter Block per unit supported. The amount of space needed for a 
block device driver is: 

(end address) - (number of units * DPB size) 

If there are multiple device drivers In a single memory Image file, the ending 
address returned by the last Initialization called Is the one PC DOS 7 uses. 
IBM recommends that all device drivers in a single memory Image file return 
the same ending address. 

If initialization of your device driver fails, and you want the system to display 
the Error in Config.Sys line # error message, set the CONFIG.SYS error 
message control flag to a non-zero value. 

Media Check Request 

Command code = 1 


Field 

Length 

Request header 

13 - BYTE 

Media descriptor from PC DOS 7 

BYTE 
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Field 

Length 

Return 

BYTE 

A pointer to the previous voiume iD (it bit 1 1 =1 and disk change is 

DWORD 

returned) 



When the command code field is 1, PC DOS 7 calls Media Check for a drive 
unit and passes its current Media Descriptor byte. See “Media Descriptor 
Byte.” Media Check returns one of the following: 

• Media not changed 

• Media changed 

• Not sure 

• Error code. 

The driver must perform the following: 

• Set the status word in the request header. 

• Set the return byte to: 

-1 for “media changed” 

0 for “not sure” 

1 for “media not changed.” 

The driver uses the following method to determine how to set the return byte: 

• If the media is nonremovable (a hard disk), set the return byte to 1. 

• If less than 2 seconds since last successful access, set the return byte to 
1 . 

• If changeline not available, set the return byte to 0. 

• If changeline is available but not active, set the return byte to 1. 

• If the media byte in the new BPB does not match the old media byte, set 
the return byte to -1 . 

• If the current volume ID matches the previous volume ID, or if the serial 
number matches the previous serial number, set the return byte to 0. 

Media Descriptor Byte 

Currently the media descriptor byte has been defined for some media types. 
This byte should be identical to the media byte if the device has the non-IBM 
format bit off. These predefined values are: 

Media descriptor 

byte — > 1 1 1 1 1 X X X 

bits — > 76543210 
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Bit 

Meaning 


0 

1 =2-sided 

0 = not 2-sided 

1 

1 = 8 sector 

0 = not 8 sector 

2 

1 =removable 

0 = not removable 

3- 7 

must be set to 

1 



Note: An exception to the above is the media descriptor byte vaiue of FO, 
which is used te indicate any media types not defined, and F9, which 
is used fer 5.25-inch media with 2 sides and 15 sectors/tracks. 

Exampies of current PC DOS 7 media descriptor bytes: 


Disk 

# 

Sectors/ 

Media 

Type 

Sides 

Track 

Descriptor 

hard disk 

- 

- 

F8H 

5.25 inch 

2 

15 

F9H 

5.25 inch 

1 

9 

FCH 

5.25 inch 

2 

9 

FDH 

5.25 inch 

1 

8 

FEH 

5.25 inch 

2 

8 

FFH 

8 inch 

1 

26 

FEH 

8 inch 

2 

26 

FDH 

8 inch 

2 

8 

FEH 

3.5 inch 

2 

9 

F9H 

3.5 inch 

2 

18 

FOH 

3.5 inch 

2 

36 

FOH 

3.5 inch Read/Write Optical 

1 

25 

FOH 


To determine whether you are using a singie-sided or a doubie-sided 
diskette, attempt to read the secend side, if an errer eccurs, yeu may 
assume the diskette is singie-sided. Media descriptor FOFi may be used fer 
those media types not described eariier. Pregrams shouid not use the media 
descriptor vaiues to distinguish media. PC DOS 7 internai routines use 
infermation in the BIOS parameter biock (BPB) to determine the media type 
of iBM-formatted diskettes. These media descripter bytes do not necessariiy 
indicate a unique media type. 

For 8-inch diskettes: 
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• FEH (IBM 3740 Format) — Single-sided, single-density, 128 bytes per 
sector, soft-sectored, 4 sectors per allocation unit, 1 reserved sector, 2 
FATs, 68 directory entries, 77*26 sectors. 

• FDH (IBM 3740 Format) — Double-sided, single-density, 128 bytes per 
sector, soft-sectored, 4 sectors per allocation unit, 4 reserved sectors, 2 
FATs, 68 directory entries, 77*26*2 sectors. 

• FEH — Double-sided, double-density, 1024 bytes per sector, soft sectored, 
1 sector per allocation unit, 1 reserved sector, 2 FATs, 192 directory 
entries, 77*8*2 sectors. 


Build BPB Request 

Command Code = 2 


Field 

Length 

Request header 

13 - BYTE 

Media descriptor from PC DOS 7 

BYTE 

Transfer address (buffer address) 

DWORD 

Pointer to BPB tabie 

DWORD 


PC DOS 7 calls Build BPB (BIOS Parameter Block) under the following two 
conditions: 

• If “Media Changed” is returned 

• If “Not Sure” is returned, there are no used buffers. Used buffers are 
buffers with changed data not yet written to the disk. 

The driver must do the following: 

• Set the pointer to the BPB 

• Set the status word in the request header. 

The device driver must determine the media type that is in the unit to return 
the pointer to the BPB table. In previous versions of IBMBIO, the FAT ID byte 
determined the structure and layout of the media. The FAT ID byte has only 
eight possible values (F8 through FF), so, as new media types are invented, 
the available values will soon be exhausted. With the varying media layouts, 
PC DOS 7 needs to be aware of the location of the FATs and directories 
before it asks to read them. 

The following paragraphs explain the method PC DOS 7 uses to determine 
the media type. 
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The information reiating to the BPB for a particuiar media is kept in the boot 
sector for the media. The foiiowing is a summary of the format of the boot 
sector. 


Field 


Length 

A 2-byte short JMP instruction (EBH), tollowed by a 

NOP instruction 

WORD 

(90H). 



Product name and version 


8 BYTES 

Bytes per sector; must be power ot 2 


WORD 

Sectors per aliocation unit; must be power of 2 


BYTE 

Reserved sectors starting at logical sector 0 


WORD 

Number ot FATs 


BYTE 

Maximum number of root directory entries 


WORD 

Totai number ot sectors in media including the boot 

sector, FAT areas, 

WORD 

and directories 



Media descriptor 


BYTE 

Number of sectors occupied by a FAT 


WORD 

Sectors per track 


WORD 

Number ot heads 


WORD 

Number ot hidden sectors 


WORD 


The BPB information contained in the boot sector starts with the Bytes per 
Sector entry. The iast three words are intended to heip the device driver 
identify the media. The number of heads is usefui for supporting different 
muitihead drives with the same storage capacity but a different number of 
surfaces. The number of hidden sectors is usefui for supporting drive 
partitioning schemes. 

For drivers that support voiume identification and disk change, this cail 
causes a new voiume identificaticn to be read from the disk. This cail 
indicates that the disk has changed in a permissible manner. 

To handle the partition that is bigger than 32MB, er one that starts beyond or 
crosses the 32MB boundary, PC DOS 7 defines an extended BPB structure. 
Depending on the size of the media, you can use either the existing BPB or 
the extended one, which contains an additional DWORD field to indicate the 
size of the partition in sectors. 

Bit 1 of the attribute field in the block device driver header indicates whether 
the device can process 32-bit secter numbers. Set bit 1 to indicate 32-bit 
suppert. 
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Field 

Length 

Bytes per sector 

WORD 

Sectors per ailocation unit 

BYTE 

Reserved sectors starting at logicai sector 0 

WORD 

Number ot FATs — 0 if not a FAT system 

BYTE 

Maximum number of root directory entries 

WORD 

Totai number ot sectors in the media. This tieid is used to detine a 
partition that is less than 32MB. Setting this field to 0 indicates to use 
the total (32-bit) number ot sectors in the media below. 

WORD 

Media descriptor 

BYTE 

Number of sectors occupied by a FAT 

WORD 

Sectors per track 

WORD 

Number ot heads 

WORD 

Number ot hidden sectors 

DWORD 

Total (32-bit) number of sectors in the media. This field is used to detine 
a partition that is greater than 32MB, or one that crosses the 32MB 
boundary. 

DWORD 


The extended BPB is a superset of the traditional BPB structure. To achieve 
the maximum compatibility between this structure and that of the traditional 
BPB, PC DOS 7 uses the following rules: 

• If the number of hidden sectors plus the total number of sectors in the 
media is greater than 64KB, use the 32-bit total number of sectors in the 
media entry (DWORD). 

• Otherwise, use the Total number of sectors in the media entry (WORD). 

A boot record exists at the beginning of each disk partition and each 
extended PC DOS 7 partition volume. PC DOS 7 automatically creates the 
extended boot record. The format of the extended boet record is: 


Field 

Length 

A 2-byte short JMP instruction (EBFI) followed by a NOP instruction 
(90H). 

WORD 

Product name and version 

8 BYTES 

Extended BPB 

25 BYTES 

Physical drive number 

BYTE 

Reserved 

BYTE 

Extended boot record signature 

BYTE 

Volume serial number 

DWORD 

Volume label 

11 BYTES 

Reserved 

8 BYTES 
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Note: The value of Extended boot record signature is 29H. The value of the 
physical drive number Is always OH or 80H. 

On all requests to extended drivers with a sector number In their request 
headers, the sector number is a DWORD. The standard PC DOS 7 block 
device drivers set the attribute bit 1 for 32-bit support. 

For each call to a device driver, PC DOS 7 checks to see if the starting sector 
number passed in the request can be supported by the device driver. If this 
value is greater than 64K for an old-style device driver, PC DOS 7 returns an 
unknown media (07H) device driver error. 

Input and Output Requests 

Command Codes = 3, 4, 8, 9, 12 (OCH) 


Field 

Length 

Request header 

13 - BYTE 

Media descriptor byte 

BYTE 

Transfer address (buffer address) 

DWORD 

Byfe/sector count 

WORD 

Starting sector number (If -1, use DWORD starting sector number. This 
entry has no meaning for a character device.) 

WORD 

For DOS 3.0 to PC DOS 7, pointer to the voiume identification if error 
code OFH is returned 

DWORD 

Starting 32-bit sector number. (Use this entry to the block device driver 
with the attribute bit 1 set.) 

DWORD 


The PC DOS 7 Input/Output request structure can process 32-bit sector 
numbers, providing support for media of more than 4 billion sectors. 

The driver must do the following: 

• Set the status word in the request header 

• Perform the requested function 

• Set the actual number of sectors or bytes transferred. 

No error checking is performed on an lOCtI call. However, the driver must 
set the return sector or byte count to the actual number of bytes transferred. 

Under certain circumstances the block device driver may be asked to do a 
WRITE operation of 64KB that seems to be a wraparound of the transfer 
address in the device driver request packet. It will only happen on WRITES 
that are within a sector size of 64KB on files that are being extended past the 
current end of file. The block device driver is allowed to ignore the balance 
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of the WRITE that wraps around. For example, a WRITE of 10000H bytes of 
sectors with a transfer address of XXXX:1 ignores the iast two bytes. 

Remember that a program using PC DOS 7 function caiis cannot request an 
input or output operation of more than FFFFH bytes because a wrap around 
in the transfer buffer segment wouid occur. Bytes wiil be ignored that wouid 
have wrapped around in the transfer segment. 

If the driver returns an error code of OFFI (invaiid Disk Change), it must 
provide a DWORD pointer to an ASCIIZ string identifying the correct voiume 
ID and the system prompts the user to reinsert the disk. 

The reference count of open files on the disk maintained by OPEN and 
CLOSE caiis ailows the driver to determine when to return error OFFI. If there 
are no open files (reference count=0) and the disk has been changed, the 
I/O is valid, and error OFH is not returned. If there are open files (reference 
count > 0) and the disk has been changed, an error OFFI situation may exist. 
PC DOS 7 IBMDOS.COM will request an OPEN or CLOSE function only if 
SFIARE is loaded. 

Nondestructive Input No Wait Request 

Command Code = 5 


Field 

Length 

Request header 

13-BYTE 

Byte read from device 

BYTE 


The driver must do the following: 

• Return a byte from the device. 

• Set the status word in the request header. 

If the character device returns busy bit = 0, meaning there are characters in 
buffer, the next character that would be read is returned. This character is 
not removed from the input buffer (that is, nondestructive input). This call 
allows PC DOS 7 to look ahead one input character. 

Character Input and Output Status Requests 

Command Codes = 6, 10 (OAH) 


Field 

Length 

Request header 

13-BYTE 
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The driver must do the following: 

• Perform the requested function. 

• Set the busy bit. 

• Set the status word in the request header. 

The busy bit is set differently for output and input. 

Output on Character Devices 

If the busy bit is 1 on return, a write request would wait for completion of a 
current request. If the busy bit is 0, no request is waiting or running. 
Therefore, a write request would start immediately. 

Input on Character Devices with a Buffer 

If the busy bit is 1 on return, a read request goes to the physical device. If 
the busy bit is 0, characters are in the device buffer and a read returns 
quickly. This also indicates that the user has typed something. PC DOS 7 
assumes that all character devices have a type-ahead input buffer. Devices 
that de not have this buffer should always return busy = 0 so that PC DOS 7 
does not loop endlessly, waiting for information to be put in a buffer that 
does not exist. 

Character Input and Output Flush Requests 

Command Codes = 7, 11 (OBH) 


Field 

Length 

Request header 

13-BYTE 


This call tells the driver to flush (terminate) all pending requests of which it 
has knowledge. Its primary use is to flush the input queue on character 
devices. 

The driver must set the status word in the Request Header upon return. 

Open and Close Requests 

Command Codes = 13 (ODH), 14 (OEH) 


Field 

Length 

Request header 

13-BYTE 


These calls are designed to give the device information about current file 
activity on the device if bit 11 of the attribute word is set. 
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On block devices, these calls can be used to manage local buffering. The 
device can keep a reference count. Every OPEN increases the reference 
count. Every CLOSE decreases the device reference count. When the 
reference count is 0, there are no open files on the device. Therefore, the 
device sheuld flush buffers inside the device to which it has written because 
the user can change the media on a removable media drive. If the media 
has been changed, reset the reference count to 0 without flushing the buffers. 

These calls are more useful on character devices. The OPEN call can send a 
device an initialization string. On a printer, the call can send a string to set 
the font or the page size so the printer is always in a known state at the start 
of an I/O stream. 

Similarly, the CLOSE call can send a post string, such as a form feed, at the 
end of an I/O stream. 

Using lOCtI to set the preliminary and ending strings provides a flexible 
mechanism for serial I/O device stream control. 

Removable Media Request 

Command Code = 15 (OFH) 


Field 

Length 

Request header 

13-BYTE 

To use this call, set bit 11 of the attribute field to 1. 

Block devices can use 


this call only by way of a subfunction of the lOCtI function call (44H). 

This call is useful because it notifies a utility if it is dealing with a removable 
or nonremovable media drive. For example, the FORMAT utility needs to 
know whether a drive is removable or nonremovable because it displays 
different versions of some prompts. 

The informatien is returned in the busy bit of the status word. If the busy bit 
is 1, the media is nonremevable. If the busy bit is 0, the media is removable. 

No error bit checking is performed. It is assumed that this call always 
succeeds. 
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Output Until Busy 

Command Code = 16 (10H) 


Field 

Length 

Request header 

13-BYTE 

T ransfer Address 

□ word 

Byte Count 

Word 

The driver must set the status in the request header. 

The actual bytes are 


transferred in the byte count word. 

This function transfers data from the specified memory buffer to a device 
until it is busy. It Is called only if bit 13 of the device attribute word is set in 
the device header. This function is not in error if it returns with the number 
of bytes transferred less than the number of bytes requested. 

Generic lOCTL Request 

Command Code = 19 (13H) 


Field 

Length 

Request header 

13-BYTE 

Major function 

BYTE 

Minor function 

BYTE 

Contents of SI 

WORD 

Contents of Dl 

WORD 

Pointer to Generic lOCTL request packet 

DWORD 


The driver must: 

• Support the functions described under Generic lOCtI request 

• Maintain its own track table (TrackLayout). 

See Appendix C, “I/O Control for Devices (lOCtI)” on page 273 for a 
description of the functions provided by generic lOCtI requests. 

Get Logical Device Request 

Command Code = 23 (17H) 


Field 

Length 

Request header length (see note below) 

BYTE 

Input (unit code) 

BYTE 
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Field 

Length 

Command code 

BYTE 

Status 

WORD 

Reserved 

8 BYTES 


Upon return, the unit code is the iast unit referenced or zero and the status 
werd is updated. 

Set Logical Device Request 

Command Code = 24 (18H) 


Field 

Length 

Request header length (see note below) 

BYTE 

Input (unit code) 

BYTE 

Command code 

BYTE 

Status 

WORD 

Reserved 

8 BYTES 


Upon return, the status word is updated. 

Note: Length vaiue inciudes the iength byte itseif. 


lOCtI Query 

Command Code = 25 (19H) 


Field 

Length 

Request header 

13-BYTE 

Major function 

BYTE 

Minor function 

BYTE 

Contents of SI 

WORD 

Contents of Dl 

WORD 

Pointer to Generic lOCtI request packet 

DWORD 


The driver must: 

• Support the functions described under Generic lOCti request 

• Maintain its own track tabie (TrackLayout). 

A driver indicates that it supports Query lOCti by setting bit 7 of the device 
attribute word, if this bit is set, the driver can be caiied, with function 19H, 
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with a standard Generic lOCtI request packet. If it is not set, the driver will 
never receive Query lOCtI calls. 

The driver should check the category code and function number in the 
request packet and return a no error signal if it can handle the call. If the 
driver cannot handle the call, It should return the Unknown Command error 
code (error code 3). Usually, a program that wants to use Generic lOCtI calls 
beyond those In DOS 3.2 will call Query lOCtIHandle or Query lOCtIDevice 
first. Then It will determine If the particular call is supported, and finally call 
the actual function. 

See Appendix C, “I/O Control for Devices (lOCtI)” on page 273 for a 
description of the functions provided by generic lOCtI requests. 
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Appendix A. PC DOS 7 Interrupts 


This chapter contains information to support use of the PC DOS 7 interrupts. 

PC DOS 7 reserves interrupt types 20H to 3FH for its use. Absoiute memory 
iocations 80H to FFH are reserved by PC DOS 7. Ali interrupt vaiues are in 
hexadecimai. 


Interrupt 20H Program Terminate 

Issue interrupt 20H to exit from a program. This vector transfers to the iogic 
in PC DOS 7 to restore the terminate address, the Ctri-Break address, and 
the critical error exit address to the vaiues they had on entry to the program. 
Ali fiie buffers are fiushed and ali handies are ciosed. You should close all 
files changed in length (see function call 10H and 3EH) before issuing this 
interrupt. If the changed file is not closed, its length, date, and time are not 
recorded correctly in the directory. 

For a program to pass a completion code or an error code when terminating, 
it must use either function call 4CH (Terminate a Process) or 31 H (Terminate 
Process and Stay Resident). These two methods are preferred over using 
interrupt 20FI, and the codes returned by them can be interrogated in batch 
processing. See function call 4CH for information on the ERRORLEVEL 
subcommand of batch processing. 

Important: Before you issue interrupt 20FI, your program must ensure that the 
CS register contains the segment address of its program segment prefix. 


Interrupt 21H Function Request 

Refer to each function call issued within 21 H in Appendix B, “PC DOS 7 
Function Calls” on page 133. 


Interrupt 22H Terminate Address 

Control transfers to the address at this interrupt location when the program 
terminates. This address is copied into the program's Program Segment 
Prefix at the time the segment is created. You should not issue this 
interrupt; the EXEC function call does this for you. 


© Copyright IBM Corp. 1995 
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Interrupt 23H Ctrl-Break Exit Address 

If the user presses the Ctrl and Break keys during standard input, standard 
output, standard printer, er asynchronous communications adapter 
operations, an interrupt 23H is executed. If BREAK is en, the interrupt 23H is 
checked on most function cails (except calis 06H and 07H). If the user-written 
Ctri-Break reutine saves aii registers, it may end with a return-from-interrupt 
instruction (IRET) to continue program execution. 

If the user-written interrupt pregram returns with a iong return, the carry fiag 
is used to determine whether the pregram wiii be ended, if the carry fiag is 
set, the program is ended, etherwise executien continues (as with a return by 
IRET). 

If the user-written Ctri-Break interrupt uses functien caiis 09H er OAH, then 
aC, carriage-return and iinefeed are eutput. If executien is continued with an 
IRET, I/O continues from the start of the line. 

When the interrupt occurs, all registers are set te the value they had when 
the original function call to PC DOS 7 was made. There are no restrictions 
on what the Ctri-Break handler is allewed te de, including PC DOS 7 function 
calls, as long as the registers are unchanged if IRET is used. 

When the program creates a new segment and loads in a second program it 
changes the Ctri-Break address. The termination of the second program and 
return to the first causes the Ctri-Break address te be restored te the value it 
had before execution of the second program. It is restored from the secend 
program's Program Segment Prefix. You should not issue this interrupt. 


Interrupt 24H Critical Error Handler Vector 

A critical error is returned when a DOS function cannot be performed. This 
error is frequently caused by a hardware condition, such as the printer being 
out of paper, a diskette drive door open, or a diskette out of space. When a 
critical errer occurs within PC DOS 7, control is transferred with an interrupt 
24H. On entry te the error handler, AH will have its bit 7=0 (high-order bit) if 
the error was a disk error (the most common occurrence), bit 7=1 if it was 
not. 

BP:SI contains the address of a Device Header Centrol Block from which 
additional information can be retrieved. See page 112. 
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The registers are set up for a retry operation, and an error code is in the 
lewer half ef the Dl register with the upper half undefined. The error codes 
follow: 


Error Code 
0 
1 
2 

3 

4 

5 

6 

7 

8 
9 
A 
B 
C 


Meaning 

Attempt to write en write-pretected diskette 

Unknown unit 

Drive not ready 

Unknown command 

Data error (CRC) 

Bad request structure length 
Seek error 
Unknown media type 
Sector not found 
Printer out of paper 
Write fault 
Read fault 
General failure 


The user stack Is in effect and contains the fellowing from top to bottom: 


IP 

CS 

FLAGS 

AX 

BX 

CX 

DX 

SI 

Dl 

BP 

DS 

ES 

IP 

CS 

FLAGS 


PC DOS 7 registers from issuing INT 24H 


User registers at time of original 
INT 21 H request 


Frem the original Interrupt 21 H 
from the user to PC DOS 7 


The registers are set such that if an IRET is executed, PC DOS 7 responds 


according to (AL) as follows: 

(AL) =0 

Ignore the error. 

= 1 

retry the operation. 

= 2 

terminate the program 


through interrupt 22H 

= 3 

fail the system call 


in progress. 
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Note: Be careful when choosing ignore as a response because this causes 
PC DOS 7 to believe that an operation has completed successfully 
when it may not have. 

To return control from the critical error handler to a user error routine, the 
following should occur: 

Before an INT 24H occurs: 

1. The user application initialization code should save the INT 24H vector 
and replace the vector with one pointing to the user error routine. 

When the INT 24H occurs: 

2. When the user error routine receives control, it should push the flag 
register onto the stack, and then execute a CALL FAR to the original INT 
24H vector saved in step 1. 

3. PC DOS 7 gives the appropriate prompt, and waits for the user input 
(Abort, Retry, Fail or Ignore). After the user input, PC DOS 7 returns 
control to the user error routine at the instruction following the CALL 
FAR. 

4. The user error routine can now do any tasks necessary. To return to the 
original application at the point the error occurred, the error routine 
needs to execute an IRET instruction. Otherwise, the user error routine 
should remove the IP, CS, and Flag registers from the stack. Control can 
then be passed to the desired point. 

Disk Errors 

If it is a hard error on disk (AH bit 7=0), register AL contains the failing drive 
number (0 = drive A, and so on). AH bits 0-2 indicate the affected disk 
area and whether it was a read or write operation, as follows: 

Bit 0 = 0 if read operation, 

1 if write operation 
Bits 2-1 (affected disk area) 

0 0 PC DOS 7 area 

0 1 file allocation table 

1 0 directory 
1 1 data area 

AH bits 3-5 indicate which responses are valid. They are: 

Bit 3=0 if FAIL is not allowed 
= 1 if FAIL is allowed 
Bit 4=0 if RETRY is not allowed 
= 1 if RETRY is allowed 
Bit 5=0 if IGNORE is not allowed 
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= 1 if IGNORE is aiiowed 


Handling of Invalid Responses 

If IGNORE is specified (AL=0) and IGNORE is not aiiowed (bit 5=0), make 
the response FAIL (AL=3). 

If RETRY is specified (AL=1) and RETRY is not aiiowed (bit 4=0), make the 
response FAiL (AL=3). 

If FAIL is specified (AL=3) and FAIL is not aiiowed (bit 3=0), make the 
response END (AL=2). 

Other Errors 

If AH bit 7=1, the error occurred on a character device, or was the resuit of 
a bad memory image of the FAT. The device header passed in BP:SI can be 
examined to determine which case exists. If the attribute byte high-order bit 
indicates a biock device, then the error was a bad FAT. Otherwise, the error 
is on a character device. 

If a character device is invoived, the contents of AL are unpredictabie and 
the error code is in Dl as above. 

Notes: 

1. Retry five times before giving this routine controi for disk errors. When 
the errors are in the FAT or a directory, retry three times. 

2. For disk errors, this exit is taken oniy for errors occurring during an 
interrupt 21 H function cail. It is not used for errors during an interrupt 
25H or 26H. 

3. This routine is entered in a disabied state. 

4. Ail registers must be preserved. 

5. This interrupt handier shouid refrain from using PC DOS 7 function caiis. 

If necessary, it may use caiis 01 H through OCH, 30H, and 59H. Use of any 
other caii destroys the PC DOS 7 stack and ieaves PC DOS 7 in an 
unpredictabie state. 

6. The interrupt handier must not change the contents of the device header. 

7. If the interrupt handier handies errors itseif rather than returning to PC 
DOS 7, it shouid restore the appiication program's registers from the 
stack, remove aii but the iast three words on the stack, then issue an 
IRET. This wili return to the program immediateiy after the INT 21 H that 
experienced the error. Note that if this is done, PC DOS 7 wiii be in an 
unstabie state untii a function cali higher than OCH is issued; therefore, it 
is not recommended. 
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The recommended way to end a critical error is to use FAIL and then test 
the extended error code of the INT 21 H. 

8. IGNORE requests (AL = 0) are converted to FAIL for critical errors that 
occur on FAT or DIR sectors. 

9. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for information on how to obtain additional error 
information. 

10. For PC DOS 7, IGNORE requests (AL=0) are converted to FAIL requests 
for certain critical errors (50-79). 

The device header pointed to by BP:SI is formatted as follows: 


DWORD Pointer to next device (FFFFH if last device) 

WORD Attributes: 

Bit 15 = 1 if character device 
= 0 if biock device 
If bit 15 is 1: 

Bit 0 = 1 if current standard input 
Bit 1 = 1 if current standard output 
Bit 2 = 1 if current NULL device 
Bit 3 = 1 if current CLOCK device 
Bit 14 is the iOCti bit 

WORD pointer to device driver strategy entry point. 

WORD pointer to device driver interrupt entry point. 

8-BYTE character device named fieid for biock devices. The first byte is the number of 
units. 


To tell if the error occurred on a block or character device, look at bit 15 in 
the attribute field (WORD at BP:SI-f4). 

If the name of the character device is desired, loek at the eight bytes starting 
at BPiSI-FlO. 


Interrupt 25H/26H Absolute Disk Read/Write 

Interrupt vectors 25H and 26H transfer control to the device driver. They 
have been extended te allew direct access to media greater than 32MB in 
size. Their use of the CX register is what distinguishes them from the 
cenventional 25H and 26H interrupts. Note that if the conventional format 
parameters are used in an attempt to access media greater than 32MB, an 
error code of 0207H is returned in AX. 

The request for extended 25H er 26H is: 
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MOV 

AL, DRIVE 

Drive number to process 

0 = A 

1 = B 

2 = C . . . 

MOV 

BX,SEG PACKET 

Parameter list 

MOV 

DS,BX 


MOV 

BX, OFFSET PACKET 


MOV 

CX,-1 

Indicates extended format 

INT 

25H or 26H 

Issue request to PC DOS 7 

POP 

AX 

Discard stack word 

JC 

ERROR 

Error code returned i n AX 


PACKET LABEL 

BYTE 

Control packet 

DO 

RBA 

RBA of first sector 
(0 origin) 

DW 

COUNT 

Number of sectors to I/O 

DO 

BUFFER 

Data buffer 


On return, the original flags are still on the stack (put there by the INT 
instruction). This is necessary because return information is passed back in 
the current flags. Be sure to pop the staok to prevent uncontrolled growth. 

Warning: If disk I/O handled by this interrupt exceeds the limit imposed by 
the 64KB direct memory access boundary, unpredictable results can occur. 
We recommend you carefully check the sector size and the number of 
sectors to be read or written to before issuing this oall. 

The number of sectors specified is transferred between the given drive and 
the transfer address. Logical sector numbers (LSN) are obtained by 
numbering each sector sequentially starting from track 0, head 0, sector 1 
(logical sector 0) and continuing along the same head, then to the next head 
until the last seotor on the last head of the traok is oounted. Thus, logical 
sector 1 is track 0, head 0, sector 2; logical sector 2 is track 0, head 0, sector 
3; and so on. Numbering continues with sector 1 on head 0 of the next track. 
Note that although the sectors are sequentially numbered (for example, 
seotors 2 and 3 on track 0 in the example above), they may not be physically 
adjacent on the disk, because of interleaving. Note that the mapping is 
different from that used by DOS version 1.10 for double-sided diskettes. 

All registers except the segment registers are destroyed by this call. If the 
transfer was successful, the carry flag (CF) is 0. If the transfer was not 
sucoessful CF=1 and (AX) indicate the error as follows. (AL) is the PC DOS 
7 error code that is the same as the error code returned in the low byte of Dl 
when an interrupt 24H is issued, and (AH) contains: 
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80H Attachment failed to respond 

40H SEEK operation failed 

OSH Bad CRC on diskette read 

04H Requested sector not found 

OSH Write attempt on write-protected diskette 

02H Error other than types listed above 

Warning: Before issuing this interrupt to removable media, the media in the 
drive must be established correctly. This can be accomplished by issuing 
either an INT 21 H Generic lOCTL (AH=44H), with a request to return the BPB 
that BUILD BPB returns; or an INT 21 H Get Current Directory (AH=47H). 


Interrupt 27H Terminate but Stay Resident 

This vector is used by programs that are to remain resident when 
COMMAND.COM regains control. 

PC DOS 7 function call 31 H is the preferred method to cause a program to 
remain resident, because this allows return information to be passed. It 
allows a program larger than 64KB to remain resident. After initializing 
itself, the program must set DX to its last address plus one, relative to the 
program's initial DS or ES value (the offset at which other programs can be 
loaded), and then execute an interrupt 27H. PC DOS 7 then considers the 
program as an extension of itself, so the program is not overlaid when other 
programs are executed. This concept is useful for loading programs such as 
user-written interrupt handlers that must remain resident. 

Notes: 

1. This interrupt must not be used by .EXE programs that are loaded into 
the high end of memory. 

2. This interrupt restores the interrupt 22H, 23H, and 24H vectors in the 
same manner as interrupt 20H. Therefore, it cannot be used to install 
permanently resident Ctrl-Break or critical error handler routines. 

3. The maximum size of memory that can be made resident by this method 
is 64KB. 

4. Memory can be used more efficiently if the block containing a copy of the 
environment is deallocated before terminating. This can be done by 
loading ES with the segment contained in 2C of the PSP, and issuing 
function call 49H (Free Allocated Memory). 

5. PC DOS 7 function call 4CH allows the terminating program to pass a 
completion (or error) code to PC DOS 7, which can be interpreted within 
batch processing (see function call 31 H). 
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6. Terminate-but-stay-resident function calls do not automatically close files. 


Interrupt 28H- 2 EH Reserved for PC DOS 7 

These interrupts are reserved for PC DOS 7 use. 


Interrupt 2FH Multiplex Interrupt 

Interrupt 2FH is the multiplex interrupt. A general interface is defined 
between two processes. The specific application using interrupt 2FH defines 
specific functions and parameters. 

Every multiplex interrupt handler is assigned a specific multiplex number. 
The multiplex number is specified in the AH register. The specific function 
that the handler is to perform is specified in the AL register. Other 
parameters are placed in the other registers, as needed. The handlers are 
chained into the interrupt 2FH interrupt vector. There is no defined method 
for assigning a multiplex number to a handler. You must pick one. To avoid 
a conflict if two applications choose the same multiplex number, the 
multiplex numbers used by an application should be patchable. 

The multiplex numbers AH=00H through BFH are reserved for PC DOS 7. 
Applications should use multiplex numbers COH through FFH. 

Note: When in the chain for interrupt 2FH, if your code calls PC DOS 7 or if 
you execute with interrupts enabled, your code must be reentrant and 
recursive. 

Interrupt 2FH Function AH=01H PRINT.COM Function Installed 
State 

The following table contains the function codes that you can specify in AL to 
request the resident portion of print to perform a specific function: 


Function 

Codes (in AL) 

Description 

0 

Get instaiied state 

1 

Submit fiie 

2 

Cancel file 

3 

Cancel all files 

4 

Status 

5 

End of status 
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Print Error Codes 

The following table contains the error codes that are returned from the 
resident portion of print. (Carry fiag is set.) 


Error 

Codes (in AX) 

Description 

1 Invalid function 

2 

File not found 

3 

Path not found 

4 

Too many open files 

5 

Access denied 

6 

Queue full 

9 

Busy 

12 

Name too long 

15 

Invalid drive 


AL = 0 Get Installed State 

This cali must be defined by aii interrupt 2FH handiers. It is used by the 
calier of the handier to determine if the handier is present. On entry, AL=0, 
AH = 1. On return, AL contains the installed state as follows: 

AL = 0 Not installed, permissible to install 

AL=1 Not installed, not permissible to install 

AL = FF Installed 

AL=1 Submit File 

On entry, AL=1, AFI = 1, and DS:DX points to the submit packet. A submit 
packet contains the level (BYTE) and a pointer to the ASCIIZ string (DWORD 
in offset segment form). The level value for PC DOS 7 is 0. The ASCIIZ 
string must contain the drive, path, and filename of the file you want to print. 
The filename cannot contain global filename characters. 

AL=2 Cancel File 

On entry, AL=2, AFI = 1, and DS:DX points to the ASCIIZ string for the print 
file you want to cancel. Global filename characters are allowed in the 
filename. 

AL = 3 Cancel all Files 
On entry, AL=3 and AH = 1. 
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AL = 4 Status 


This call holds the jobs in the print queue so that you can scan the queue. 
Issuing any other code releases the jobs. On entry, AL=4, AH = 1. On 
return, DX contains the error count. The error count is the number of 
consecutive failures PRINT had while trying to output the last character. If 
there are no failures, the number is 0. DS:SI points to the print queue. The 
print queue consists of a series of filename entries. Each entry is 64 bytes 
long. The first entry in the queue is the file currently being printed. The end 
of the queue is marked by a queue entry having a null as the first character. 

AL = 5 End of Status 

Issue this call to release the queue from call 4. On entry, AL=5 and AH = 1. 
On return, AX contains the error codes. For information on the error codes 
returned, refer to “Print Error Codes” on page 116. 

AL = F8 -FF Reserved by PC DOS 7 

Interrupt 2FH Function AH=06H Get ASSIGN.COM Installed 
State 

(AL=0) is supported. 

Interrupt 2FH Function AH=10H Get SHARE.EXE Installed State 

AH = 10H is the resident part of SHARE. The Get Installed State function 
(AL=0) is supported. 

Interrupt 2FH Function AX=1680H DOS Idle Call 

Many applications execute busy loops. This is usually while the application 
waits for the user to type something or to respond in some way. Informing 
the operating system that the application is idle offers some benefits: 

• Power-management software can make decisions about how to conserve 
energy on the system. 

• Multitasking software can save time by not giving CPU cycles to tasks 
that are idle. 

This API (applications program interface) should be used by all PC DOS 7 
applications to indicate when they are idle. To prevent halting the system, 
applications should check the Int 2FH vector to see that it is not zero before 
issuing the first idle call. If the API is supported in the environment you are 
in, the Int 2FH will return with AL=0; otherwise, it will return with AL 
unchanged (80H). Applications are not usually interested in the return value. 
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This API is non blocking. This means an application's execution would 
continue after issuing this API. Yeur program should contain an idle loep 
that re-issues this interrupt if the application stays in the idle state. 

DOSDOCK API 

In order to provide cemmunicatien between the PC DOS 7 docking support 
programs some new multiplex interrupt functiens are being defined in PC 
DOS 7. The following API's are defined and used for docking support in PC 
DOS 7. 

Interrupt 2FH Function 2000H - Check DOSDOCK Installation 

This function is being defined to allow a caller to determine if the DOSDOCK 
pregram is resident. 

Called with: 

AX = 2000H 

Returns: 

AL = OOH DOSDOCK program not installed 
AL = FFH DOSDOCK program resident 

Interrupt 2FH Function 2001H - Get Docking Event 

This function allows the caller to determine if a decking event has occured. 

An application can use this interrupt to determine if a docking event has 
occured rather than poll the PnP Bios. After making this call the event flag is 
reset to 0. 

Called with: 

AX = 2001H 

Returns: 

AL = OOH No Event 

AL = OlH Docking Event Occured 

AL = 21H Undocking Event Occured 

Interrupt 2FH Function 2002H - Get Current Dock Status 

This function returns the current dock state (docked or undocked). An 
application can use this interrupt to determine the current deck state ef the 
machine. This flag is modified when a docking event occurs to the new dock 
state. 

Called with: 

AX = 2002H 

Returns: 

AL = OOH Machine is not Docked 
AL = OlH Machine is Docked 
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Interrupt 2FH Function AX=43E0H DOS Protected Mode 
Services Check 

Please refer to Appendix E, “DOS Protected Mode Services” on page 313 for 
details of this function call along with the Interrupt 31 H calls to the DPMS 
driver. 
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Interrupt 2FH Advanced Power Management Driver 

All power management functions are accessed through subfunctions of 
Interrupt 2FH, functlen 54H and 53H. The following table lists the 
subfunctiens. In all calls, undefined bits are reserved and should be set to 0. 

The following INT 2Fh APIs (Application Program Interfaces) are defined for 
DOS APM driver (POWER.EXE) which Is APM 1.0 compliant. 


INT 2F 

Function 

Description 

5400 

Detect POWER.EXE 

5401 

Get or set power status 

5402 

Get or set idle detection strategy 

5403 

Get or set power saving level 

5481 

Get idle statistics 

5482 

Get or set APM polling frequency 


The DOS INT 2Fh APIs for APM driver (POWER.EXE) that Is 1.1 cempllant do 
not exist from the APM Committee (Microsoft and Intel). The intent of this 
document is te propose a standard for APM driver (POWER.EXE 1.01), INT 
2Fh APIs that can utilize APM 1.1 BIOS functionality. The following are the 
DOS INT 2Fh APIs that are proposed as a standard for APM driver. 


INT 2F 

Function 

Description 

530C 

PM Event First Phase Broadcast 

5404 

Get Device Power State 

5405 

Set Device Power State 

5406 

Enable/Disable device power state 

5407 

Engage/Disengage power management 


The intent of these API's is to give POWER.EXE control over specific unit 
device, thus resulting in a greater savings to the system unit battery life as 
compared to an application coded to the POWER.EXE 1.0 API's. 


Interrupt 2FH Function AX=530BH PM Event Broadcast 

ENTRY: 


AX 530BH 


BX OOOlh 

; System standby request 

0002 h 

; System suspend request 

0003 h 

; Normal Resume notification 

0004h 

; Critical Resume notification 

0005h 

; Battery low notification 
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EXIT: 


* 

0006h 

* 

0007h 

■k 

0008h 

■k 

0009h 

■k 

OOOAh 

■k 

OOOBh 

BH 

80h 


0 


Power Status Change Notification (1.1) 
Update Time Notification (1.1) 
Critical System Suspend Notification (1.1) 
User System Standby Request Notification (1.1) 
User System Suspend Request Notification (1.1) 
System Standby Resume Notification (1.1) 


; An application has rejected the 
system standby or request. 

; Otherwise 


POWER polls the APM firmware periodically for messages. These messages 
are sent to all applicable APM applications. The broadcasted message Is an 
INT 2FH, function 530BH. When POWER polls the APM firmware and detects 
a request to switch to the system standby or suspend states, the POWER 
device driver broadcasts this message and waits for this interrupt to return. 
Handlers of this interrupt can reject these two request. When a request is 
rejected by setting BH=80H, POWER sends a state change message to the 
APM firmware. The APM firmware might still change power states In a 
critical power situation. 


An application that receives a system or standby request might choose to 
reject it if the application is in a critical section of code. In some other 
cases, it will prepare for suspend by saving its state and then passing on the 
request. Any handler of this message must pass it down the INT 2FH chain 
(even when rejecting the request). This notifies the other handlers of the 
request. Even when a request has been rejected, APM might still choose to 
enter the suspend state (particularly in a critical low power situation). 


The three notifications (normal resume, critical resume, and battery low) also 
might cause applications to respond. 

All undefined bits are reserved and should be ignored until they are defined. 

Note: This interrupt is provided only for passing on information. It is sent 
during a timer tick. So, processing this interrupt should be as fast as 
possible. Applications in a critical state should reject this call and 
should not attempt to do any maintenance work that results in an 
inordinate delay during the interrupt. Calling DOS or ROM bios 
functions is not allowed. 
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Interrupt 2FH Function AH=530CH PM Event First Phase 
Broadcast (1.1) 

ENTRY: 


EXIT: 


AX 

530CH 


BX 

000 Ih 

; Systeni_Standby_0K 


0002h 

; Systeni_Suspend_0K 


0009h 

; User_Systeni_Standby_0K 


OOOAh 

; User_Systeni_Suspend_0K 

BH 

80h 

; An application has rejectr 


Otherwi se 


1.1 compliant: 


The PM Event First Phase Broadcast (INT 2Fh, AX = 530Ch) API is defined 
for POWER.EXE 1.01 that broadcasts first phase PM events for the two phase 
protocoi. The foilowing definition aiiows consistency to the PM events 
defined at INT 15h level. 


Accessing POWER.EXE Controls 

Detect POWER.EXE 

ENTRY: 


AX 

5400H 


AX 

5400H 

;If POWER.EXE is not installed 


Version number 

;If POWER.EXE is installed 

BH 

50H 

; ASCI I “P” character 

BL 

4DH 

; ASCI I “M” character 


This call must be made before any calls are made to other APIs. This is 
done to ensure that calls to POWER are only made when the driver is 
present. 

Get or Set Power Status 

ENTRY: 


AX 

540IH 

Get or set power status 

BH 

0 

Get power status 


1 

Set power status 

BL 

Bit 0 

POWER.EXE power management 
switch (0=off, I=on) 


Bit 1 

APM firmware power management 
switch (0=off, l=on) 
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Bits 2-7 


; Reserved (set to 0) 


EXIT: 


AX 0 
02H 
OSH 
87H 
BL 
BH 


Operation successful 
ERROR_PM_ALREADY_CONNECTED 
ERROR_PM_NOT_CONNECTED 
ERROR_PM_INVALID_PARAMETER 
Current power status 
Power status before cal 1 


This function allows selection among any of the combinations of software and 
hardware power management ON or OFF, as follows: 

• POWER=0, APM=0 - Function for all power management is disabled. 

This is equivalent to POWER OFF. 

• POWER=0, APM = 1 - Power management at the software level is 
disabled. Software idle detection and APM event broadcast to 
applications are disabled. APM firmware power management is enabled. 
This is equivalent to POWER STD. 

• POWER=1, APM = 1 - This is true advanced power management. 
Bidirectional communication between POWER.EXE and the APM firmware 
is established. POWER.EXE will send CPU_IDLE messages while the 
APM firmware is posting power events to be read and broadcasted by 
POWER.EXE. This is equivalent to POWER ADV. 


If there is no APM firmware, APM = 1 is ignored 


Get or Set Idle Detection Strategy 

ENTRY: 


AX 

5402H 

BH 

0 


1 

BL 

Bit 0 


Bit 1 

Bit 2 


Bi t 3 
Bits 4-7 


EXIT: 

BX 


Get or set idle detection strategy 
Get current strategy 
Set current strategy 
Use INT 16H function I/ll 
(keyboard idle) 

Use INT 28H (DOS idle) 

Use INT 2FH function 1680 
(application) 

Use INT 2AH 
Reserved 


;Current savings level (1-8) 
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Interrupt 2FH triggers as soon as it is received. Interrupts 16H and 28H are 
monitored over a period of time. The interrupt (16H or 28H) that occurs most 
often is the one used to trigger idies. 

An entry vaiue of OFFH in BL enabies ail strategies. A vaiue of 0 disabies 
idie detection through these interrupts (but broadcast of PM events is 
enabied). Use get or set power status to enabie or disabie power 
management. 


Get or Set POWER Saving Level 

ENTRY: 


Get or set power saving level 
Get current saving level 
Set saving level to given number 

EXIT: 


MA 

BX 


0‘rujn 

0 

1-8 


AX 0 ;0peration successful 

BX ;Current saving level 

There are 8 different defined power saving ieveis (1-8). Levei 1 is the ievei 
where the ieast power savings are reaiized. Levei 8 is the highest. The 
defauit POWER device driver defines ADV:MAX as ievei 7, ADViREG as ievei 
6, and ADViMIN as ievei 3. This APi controis two parameters: 

• The BaseLineMax for the INT 16H idie detection 

• The spread of INT 16H timings over the current Baseline (noise) 

The foliowing tabie shows the current assignments for each ievei: 


Level 

Base Line % 

Noise/spread % 

1 

222 

12.5 

2 

250 

25 

3 

285 

37.5 

4 

333 

50 

5 

400 

62.5 

6 

500 

75 

7 

750 

87.5 

8 

1000 

100 
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Get Device Power State (1.1) 

ENTRY: 


AX 

BX 


EXIT: 


5404h 

Power Device ID 


OOOIh 

Olxxh 

02xxh 

OSxxh 

04xxh 

OSxxh 

OSxxh 

EOOOh 



All 

AX 

0 


03h 

** 

04h 

** 

05h 

** 

06h 

cx 



All devices power managed by APM BIOS 
Di spl ay 

Secondary Storage 
Parallel Ports 
Seri al Ports 
Network Adapters 
PCMCIA Sockets 
EFFFh 

: OEM defined device IDs 


Operation successful 
ERROR_PM_NOT_CONNECTED 
ERROR_PM_NOT_ENGAGED 
ERROR_PM_NOT_ENABLED 
ERR0R_PM_I N VALI D_DEV I C E_I D 
device power state 


Note: ** - New error code for POWER.EXE driver. 

The following INT 2Fh API returns the power state for the system or device 
specified in the power device ID. The power state value returned when the 
power device ID specified indicates "all devices power managed by the APM 
BIOS" or "all devices in a class" is defined only when that power device ID 
has been used in a call to Set Device Power State (INT 2Fh, AX = 5405). In 
the case where the power device ID has not been used in a call to Set 
Device Power State, the function will be unsuccessful and will return error 
code 06 (ERROR_PM_INVALID_DEVICE_ID). 


Set Device Power State (1.1) 

ENTRY: 


AX 

BX 


5405h 

Power Device ID 


OOOIh 

Olxxh 

02xxh 

03xxh 

04xxh 

OSxxh 

OSxxh 

EOOOh 


All devices power managed by APM BIOS 
Di spl ay 

Secondary Storage 
Parallel Ports 
Seri al Ports 
Network Adapters 
PCMCIA Sockets 
EFFFh 
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; OEM defined device IDs 

All other values reserved where xxh = unit number (0 based) 
CX Device Power State 



OOh 

APM Enabled 


Olh 

Standby 


02h 

Suspend 


03h 

Off 

AX 

0 

Operation successful 


03h 

ERROR PM NOT CONNECTED 

** 

04h 

ERROR PM NOT ENGAGED 

** 

05h 

ERROR PM NOT ENABLED 

** 

06h 

ERROR PM INVALID DEVICE ID 


87h 

ERROR PM INVALID PARAMETER 


Note: ** - New error code for POWER.EXE driver. 

The following INT 2Fh API sets the system or device specified in the power 
device ID into the requested power state. 


Enable/Disable device power state (1.1) 


ENTRY: 

AX 

5406h 



BX 

Power Device ID 



OOOIh 

All devices power managed by APM BIOS 



Olxxh 

Di spl ay 



02xxh 

Secondary Storage 



03xxh 

Parallel Ports 



04xxh 

Seri al Ports 



OSxxh 

Network Adapters 



06xxh 

PCMCIA Sockets 



EOOOh - EFFFh 




OEM defined device IDs 



All other values reserved where xxh = unit number (0 based) 


CX 

OOOOh 

Disable device power state 



OOOIh 

Enable device power state 

EXIT: 

AX 

0 

Operation successful 



03h 

ERROR PM NOT CONNECTED 


** 

04h 

ERROR PM NOT ENGAGED 


** 

05h 

ERROR PM NOT ENABLED 


** 

06h 

ERROR PM INVALID DEVICE ID 



87h 

ERROR PM INVALID PARAMETER 


Note: ** - New error code for POWER.EXE driver. 
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The following INT 2Fh API will enable or disable power management for a 
specified device. When disabled the APM BIOS dees not automatically 
power manage the device. 

Engage/Disengage power management (1.1) 


ENTRY: 

AX 

5407h 



BX 

Power Device ID 



OOOIh 

All devices power managed by APM BIOS 



Olxxh 

Di spl ay 



02xxh 

Secondary Storage 



OSxxh 

Parallel Ports 



04xxh 

Seri al Ports 



OSxxh 

Network Adapters 



06xxh 

PCMCIA Sockets 



EOOOh - EFFFh 




OEM defined device IDs 



All other values reserved where xxh = unit number (0 based) 


CX 

OOOOh 

Disengage power management 



OOOIh 

Engage power management 

EXIT: 

AX 

0 

Operation successful 



03h 

ERROR PM NOT CONNECTED 


** 

05h 

ERROR PM NOT ENABLED 


** 

06h 

ERROR PM INVALID DEVICE ID 



87h 

ERROR PM INVALID PARAMETER 


Note: ** - New error code for POWER.EXE 1.01 driver. 

The following INT 2Fh API will engage/disengage power management ef the 
system or device. When disengaged, the APM BIOS automatically pcwer 
manages the system cr device. 

Get Statistics 

ENTRY: 

AX 

DS:SI 
BX 

CX 

EXIT: 

AX 


548 IH 

0 

1 

ICH 


Get statistics 

Point to buffer for statistics 
Get idle detection statistics 
Get APM statistics 
Buffer size in bytes 


;0peration successful 
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71H ;ERROR_PM_BUFFER_TOO_SMALL 

87H ;ERROR_PM_INVALID_PARAMETER 

This function returns either a structure detailing the efficiency and strategy of 
power usage or a count of APM resumes. The following structures are the 
idle detection and APM statistics blocks. 


STAT_INF0 struc 
CPU_ON_TIME dd ? 

CPU_IDLE_TIME dd ? 

TOTAL_IDLE_CALLS dd ? 

TOTAL_APP_IDLE dd ? 

T0TAL_D0S_YIELD dd ? 

TOTAL_KEY_IDLE dd ? 

T0TAL_D0S_IDLE dd ? 

STAT INFO ends 


Idle detection statistics 
Total time CPU is active 
(TIMER TICS) 

Total time CPU is idle 
(TIMER TICS) 

Total count D0_IDLE 
executed through INT 2FH 
Total count D0_IDLE 
executed through INT 28H 
Total count D0_IDLE 
executed through INT 16H 
Total count D0_IDLE 
executed through INT 2AH 


APM_STATS struc 
RESUME_COUNT 

APM STATS ends 


dw ? 


APM statistics 

Total number of resumes 

since last APM ENABLE 


The CPU_ON_TIME value does not Include timer ticks which occur while Idle 
detection In POWER is disabled. 


Get or Set APM Polling Period 

ENTRY: 


AX 

5482H 

;Get or set APM polling 

peri od 

BX 

0 

;Get APM polling period 



non zero 

;Set APM polling period 

Val ue 


equals polling period to set 


EXIT: 


AX 

0 

;0peration successful 

BX 


; Current APM polling period 


This function sets or returns the period at which POWER polls the APM 
firmware for PM events. The value Is the number of timer ticks between 
polls. 
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APM Error Return Codes and Descriptions 

The error codes that are defined for POWER.EXE device driver for APM 1.0 
are as foiiows. 

02h ; ERROR_PM_ALREADY_CONNECTED 

03h ; ERR0R_PM_N0T_C0NNECTED 

71h ; ERR0R_PM_BUFFER_T00_SMALL 

87h ; ERROR_PM_INVALID_PARAMETER 

The foiiowing new error codes are defined for the POWER.EXE 1.01 device 
driver to utiiize APM 1.1 BIOS functionality. 

04h ; ERR0R_PM_N0T_ENGAGED 

05h ; ERR0R_PM_N0T_ENABLED 

06h ; ERROR_PM_INVALID_DEVICE_ID 

07h ; ERR0R_PM_DEVIDN0TSET 

Interrupt 2FH Function AH=0B7H Get APPEND.EXE Installed 
State 

AH = B7H is the resident part of APPEND. The Get Instaiied State function 
(AL=0) is supported. 

AL=2 is the Get APPEND version. This caii is for distinguishing between the 
PC LAN APPEND and the DOS APPEND. On return, if AX=FFFFH then the 
DOS APPEND is loaded. 

AL=4 is the Get APPEND Path Pointer (DOS APPEND oniy). On return ES:Di 
points to the currentiy active APPEND path. 

AL=6 is the Get APPEND Function State (DOS APPEND oniy). 

BX is returned with bits set indicating if APPEND is currentiy enabled and 
what functions are in effect. 


Bit 

Function in effect if bit is on 

0 

APPEND enabied 

13 

/PATH 

14 

/E 

15 

IX 


Note: The functions in effect do not change whether or not APPEND is 
disabied. 

AL=7 Set function state (DOS APPEND 
oniy) 
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On input BX is the new setting for all functions. 

The suggested procedure Is to get the current functlen 
state, turn on or turn off the desired bits, then 
use this call to set the function state. 

AL=11H Set Return Feund Name State (DOS APPEND 
only) 

On request AL=17, a prccess system state flag Is set. If this flag is set, then 
on the next ASCIIZ SDH, 43H or 6CH function call within Interrupt 21 H that 
APPEND processes, APPEND returns the name It finds to the application 
filename buffer. This name may be different from the one the applicaticn 
offered. The application must provide enough space for the found name. 

After APPEND has prccessed an Interrupt 21 H, it resets the Return Found 
Name state. The following is an example of this process. 


MOV 

AH,0B7H 

; Indicate APPEND 

MOV 

AL,0 

; Get installed state 

INT 

2FH 


CMP 

AL,0 

; APPEND installed? 

JE 

NOT_INSTALLED 


MOV 

AH,0B7H 

; Indicate APPEND 

MOV 

AL,2 

; Get APPEND version 

INT 

2FH 


CMP 

AX, -I 

; DOS version? 


PC LAN APPEND 

; AX<> -I means PC LAN 

ONE 

APPEND 


1 owi ng 

functions are 

(/alid only if PC DOS 7 APPEND 

MOV 

AH,0B7H 

; Indicate APPEND 

MOV 

AL,4 

; Get APPEND path pointer 

INT 

2FH 

; ES:DI = address of APPEND path 
; (Buffer is 128 characters long) 

MOV 

AH,0B7H 

; Indicate APPEND 

MOV 

AL,6 

; Get function state 

INT 

2FH 



BX = function state 
8000H = /X is on 
4000H = /E is on 
2000H = /PATH is on 
OOOIH = APPEND enabled 
If off, simi 1 ar to nul 1 


130 PC DOS 7 



APPEND path 

Set on by any non-status 
occurrence of APPEND 


MOV 

AH,0B7H 

; Indicate APPEND 

MOV 

AL,7 

; Set function state 

MOV 

BX, state 

; New state 

INT 

2FH 


MOV 

AH,0B7H 

; Indicate APPEND 

MOV 

AL,11H 

; Set Return Found 
; Name state 

INT 

2FH 



Example 2FH Handler 

MYNUM DB X ; X = The specific AH 

; multiplex number. 

INT_2F_NEXT DD ? ; Chain location 

INT_2F: 

ASSUME DS:NOTHING,ES:NOTHING,SS:NOTHING 


CMP 

AH, MYNUM 


JE 

MINE 


JMP 

INT 2F NEXT 

; Chai n to next 
; 2FH Handler 

MINE: 

CMP 

AL,0F8H 


JB 

D0_FUNC 


IRET 


; IRET on reserved 
; functions 

D0_FUNC: 

OR 

AL,AL 


JNE 

NON_INSTALL 

; Non Get Installed 
; State request 

MOV 

AL,0FFH 

; Say Tm here 

IRET 


; A1 1 done 


NON_INSTALL: 
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Installing the Handler 

The following example centains the functions necessary to install a handler: 


MOV 

AH,MYNUM 

XOR 

AL,AL 

INT 

2FH 

OR 

AL,AL 

JZ 

OK INSTALL 


; Ask if already 
; installed 


BAD_INSTALL: 


Handler already installed 


OK_INSTALL: 


; Install my 
; handler 


MOV AL,2FH 

MOV AH,GET_INTERRUPT VECTOR 

INT 21H 

MOV WORD PTR INT_2F NEXT+2,ES 

MOV WORD PTR INT_2F_NEXT,BX 

MOV DX, OFFSET INT_2F 

MOV AL,2FH 

MOV AH,SET_INTERRUPT_VECTOR 

INT 2IH 


Get multiplex 
vector 


Set multiplex 
vector 


Interrupt 30H-3FH Reserved for PC DOS 7 

These interrupts are reserved for PC DOS 7 use. 
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Appendix B. 

PC DOS 7 Function Calls 

Number 

Function Name 

OOH 


Program terminate 

01 H 


Console input with echo 

02H 


Display output 

OSH 


Auxiliary input 

04H 


Auxiliary output 

OSH 


Printer output 

06H 


Direct console I/O 

07H 


Direct console input without echo 

OSH 


Console input without echo 

09H 


Display string 

OAH 


Buffered keyboard input 

OBH 


Check standard input status 

OCH 


Clear keyboard buffer, invoke a keyboard function 

ODH 


Disk reset 

OEH 


Select disk 

OFH 


Open file 

10H 


Close file 

11H 


Search for first entry 

12H 


Search for next entry 

13H 


Delete file 

14H 


Sequential read 

15H 


Sequential write 

16H 


Create file 

17H 


Rename file 

18H 


Reserved by PC DOS 7 

19H 


Current disk 

1AH 


Set disk transfer address 

1BH 


Allocation table information 

1CH 


Allocation table information for specific device 

1DH 


Reserved by PC DOS 7 

1EH 


Reserved by PC DOS 7 

1FH 


Get Default Drive Parameter Block 

20H 


Reserved by PC DOS 7 

21 H 


Random read 

22H 


Random write 

23H 


File size 

24H 


Set relative record field 

25H 


Set interrupt vector 

26H 


Create new program segment 

27H 


Random block read 
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28H Random block write 

29H Parse filename 

2AH Get date 

2BH Set date 

2CH Get time 

2DH Set time 

2EH Set or reset verify switch 

2FH Get disk transfer address 

30H Get PC DOS 7 version number 

31H Terminate process and remain resident 

32H Get Drive Parameter Block 

33H Get or Set system value 

34H Get InDOS Flag Address 

35H Get interrupt vector 

36H Get disk free space 

37H Reserved by PC DOS 7 

38H Get or set country dependent information 

39H Create subdirectory (MKDIR) 

3AH Remove subdirectory (RMDIR) 

3BH Change current directory (CHDIR) 

3CH Create a file (CREAT) 

3DH Open a file 

3EH Close a file handle 

3FH Read from a file er device 

40H Write to a file or device 

41H Delete a file from a specified directory (UNLINK) 

42H Move file read/write pointer (LSEEK) 

43H Change file mode (CHMOD) 

44H I/O control for devices (lOCtI) 

45H Duplicate a file handle (DUP) 

46H Force a duplicate of a file handle (FORCDUP) 

47H Get current directory 

48H Allocate memory 

49H Free allecated memory 

4AH Modify allocated memory blocks (SETBLOCK) 

4BH Load or execute a program (EXEC) 

4CH Terminate a process (EXIT) 

4DH Get return code ef a subprocess (WAIT) 

4EH Find first matching file (FIND FIRST) 

4FH Find next matching file (FIND NEXT) 

50H Set Program Segment Prefix Address 

51H Get Program Segment Prefix Address 

52H Reserved by PC DOS 7 

53H Reserved by PC DOS 7 
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54H 

Get verify setting 

55H 

Reserved by PC DOS 7 

56H 

Rename a file 

57H 

Get or set a file's date and time 

5800H 

Get Allocation Strategy 

5801 H 

Set Allocation Strategy 

5802H 

Get Upper-Memory Link 

5803H 

Set Upper-Memory Link 

59H 

Get extended error 

5AH 

Create unique file 

5BH 

Create new file 

5CH 

Lock or unlock file access 

5D0AH 

Set Extended Error 

5E00H 

Get machine name 

5E02H 

Set printer setup 

5E03H 

Get printer setup 

5F02H 

Get redirection list entry 

5F03H 

Redirect device 

5F04H 

Cancel redirection 

60H 

Reserved by PC DOS 7 

61 H 

Reserved by PC DOS 7 

62H 

Get PSP address 

63H 

Reserved by PC DOS 7 

64H 

Reserved by PC DOS 7 

65H 

Get extended country information 

66H 

Get or set global code page 

67H 

Set handle count 

68H 

Commit file 

69H 

Reserved by PC DOS 7 

6AH 

Reserved by PC DOS 7 

6BH 

Reserved by PC DOS 7 

6CH 

Extended open or create 


Using PC DOS 7 Function Caiis 

Most function calls require input to be passed to them in registers. After 
setting the appropriate register values, issue the function calls in either of 
the following ways: 

• The preferred method is to place the function number in AH and issue 
interrupt 21 H. 

• Place the function number in AH and execute a call to offset 50H in your 
program segment prefix. 
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Program Code Fragments 

In each of the function call descriptions in this chapter, the input, output and 
method of use are described using a small program code fragment. These 
fragments are written in IBM PC Assembler Language. 

.COM Programs 

The descriptions assume that the program is an .EXE, not a .COM program. 
If a .COM program is desired, do not include either of the following 
instructions: 

MOV ES,SEG - 
or 

MOV DS,SEG - 


Notes: 

1. Some FCB function calls do not permit invalid characters (0DH-29H). 

2. Device names cannot end in a colon. 

3. The contents of the AX register can be altered by any of the function 
calls. Even though no error code is returned in AX, it is possible that AX 
has been changed. 


PC DOS 7 Registers 

PC DOS 7 uses the following registers, pointers, and flags when executing 
interrupts and function calls: 


Register 

General 

Definition 

Registers 

AX 

Accumulator (16-bit) 

AH 

Accumulator high-order byte (8-bit) 

AL 

Accumulator low-order byte (8-bit) 

BX 

Base (16-bit) 

BH 

Base high-order byte (8-bit) 

BL 

Base low-order byte (8-bit) 

CX 

Count (16-bit) 

CH 

Count high-order byte (8-bit) 

CL 

Count low-order byte (8-bit) 

DX 

Data (16-bit) 

DH 

Data high-order (8-bit) 

DL 

Data low-order (8-bit) 

Flags 

OF,DF,IF,TF,SF,ZF,AF,PF,CF 
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Register 


Definition 

Pointers 

SP 

Stack pointer (16-bit) 

BP 

Base pointer (16-bit) 

IP 

Instruction pointer (16-bit) 


Register 

Segment 

Definition 

Registers 

CS 

Code segment (16-bit) 

DS 

Data segment (1 6-bit) 

SS 

Stack segment (16-bit) 

ES 

Extra segment (16-bit) 


Register 

Index 

Definition 

Registers 

Dl 

Destination index (16-bit) 

SI 

Source index (16-bit) 


Register Numbering Convention 

Each register is 16 bits iong and is divided into a high and low byte. Each 
byte is 8 bits long. The bits are numbered from right to left. The low byte 
contains bits 0 through 7 and the high byte contains bits 8 through 15. The 
chart below shows the hexadecimal values assigned to each bit. 



Fligh Byte 

Low Byte 

Bit 

15 14 13 12 11 10 9 8 

7 6 5 4 3 2 1 0 

Flex value 

8 4 2 1 8 4 2 1 

8 4 2 1 8 4 2 1 


PC DOS 7 Internal Stack 

When PC DOS 7 gains control, it switches to an internal stack. User 
registers are preserved unless information is passed back to the requester 
as indicated in the specific requests. The user stack needs to be sufficient to 
accommodate the interrupt system. It is recommended that the user stack 
be 200H in addition to what the user needs. 
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Responding to Errors 

Handle function calls report an error by setting the carry flag and returning 
the error code in AX. FCB function calls report an error by returning FFH in 
AL. 

Extended error support (59H) provides a common set of error codes and 
speoific error information such as error classification, looation, and 
reoommended aotion. In most critical cases, applications can analyze the 
error code and take specific action. Reoommended actions are intended for 
programs that do not understand the error oodes. Programs oan take 
advantage of extended error support both from interrupt 24H critical error 
handlers and after issuing interrupt 21 H funotion calls. Do not code to 
speoific error oodes. 


Extended Error Codes 


Hexadecimal 

Code 

Decimal 

Code 

Meaning 

01 H 

1 

Invalid function number 

02H 

2 

File not found 

OSH 

3 

Path not found 

04H 

4 

Too many open files (no handles left) 

OSH 

5 

Access denied 

06H 

6 

Invalid handle 

07H 

7 

Memory control blocks destroyed 

OSH 

8 

Insufficient memory 

09H 

9 

Invalid memory block address 

OAH 

10 

Invalid environment 

OBH 

11 

Invalid format 

OCH 

12 

Invalid access code 

ODH 

13 

Invalid data 

OEH 

14 

Reserved 

OFH 

15 

Invalid drive was specified 

10H 

16 

Attempt to remove the current directory 

1 1 H 

17 

Not same device 

12H 

18 

No more files 

13H 

19 

Attempt to write on write-protected diskette 

14H 

20 

Unknown unit 

15H 

21 

Drive not ready 

16H 

22 

Unknown command 

17H 

23 

Cyclic redundancy check (CRC) — part of diskette is 
bad 

18H 

24 

Bad request structure length 

19H 

25 

Seek error 

1 AH 

26 

Unknown media type 

1 BH 

27 

Sector not found 

1CH 

28 

Printer out of paper 

1 DH 

29 

Write fault 

1EH 

30 

Read fault 

1 FH 

31 

General failure 

20H 

32 

Sharing violation 
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Hexadecimal 

Decimal 


Code 

Code 

Meaning 

21 H 

33 

Lock violation 

22H 

34 

Invalid disk change 

23H 

35 

FCB unavailable 

24H 

36 

Sharing buffer overflow 

25H 

37 

Reserved by PC DOS 7 

26H 

38 

Unable to complete file operation 

27H-3 1 H 

39-4 9 

Reserved by PC DOS 7 

32H 

50 

Network request not supported 

33H 

51 

Remote computer not listening 

34H 

52 

Duplicate name on network 

35H 

53 

Network path not found 

36H 

54 

Network busy 

37H 

55 

Network device no longer exists 

38H 

56 

NETBIOS command limit exceeded 

39H 

57 

System error; NETBIOS error 

3AH 

58 

Incorrect response from network 

3BH 

59 

Unexpected network error 

3CH 

60 

Incompatible remote adapter 

3DH 

61 

Print queue full 

3EH 

62 

Not enough space for print file 

3FH 

63 

Print file was cancelled 

40H 

64 

Network name was deleted 

41 H 

65 

Access denied 

42H 

66 

Network device type incorrect 

43H 

67 

Network name not found 

44H 

68 

Network name limit exceeded 

45H 

69 

NETBIOS session limit exceeded 

46H 

70 

Sharing temporarily paused 

47H 

71 

Network request not accepted 

48H 

72 

Print or disk redirection is paused 

49H- 4 FH 

73-7 9 

Reserved 

50H 

80 

File exists 

51 H 

81 

Reserved 

52H 

82 

Cannot make directory entry 

53H 

83 

Fail on INT 24 

54H 

84 

Too many redirections 

55H 

85 

Duplicate redirection 

56H 

86 

Invalid password 

57H 

87 

Invalid parameter 

58H 

88 

Network data fault 

59H 

89 

Function not supported by network 

5AH 

90 

Required system component not installed 

Error Classes 



Hexadecimal 

Decimal 


Value 

Value 

Description 

01 H 

1 

Out of Resource: Example: out of space or channels. 

02H 

2 

Temporary Situation: Something expected to disappear 
with time. This is not an error condition, but a 
temporary situation such as a locked file. 

03H 

3 

Authorization: Permission problem. 
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Hexadecimal Decimal 


Value 

Value 

Description 

04H 

4 

Internal: Internal error in system software. Probable 
problem with system software rather than a user or 
system failure. 

OSH 

5 

Hardware Failure: A serious problem not the fault of 
user program. 

06H 

6 

System Failure: Serious failure of system software not 
the fault of the user, such as missing or incorrect 
configuration files. 

07H 

7 

Application Program Error: Inconsistent requests. 

OSH 

8 

Not Found: File or item not found. Inconsistent 
requests. 

09H 

9 

Bad Format: File or value in invalid format or type; 
unsuitable. 

OAH 

10 

Locked: Locked file or item. 

OBH 

11 

Media: Media failure such as incorrect disk, CRC error, 
or defective media. 

OCH 

12 

Already Exists: Duplication error, such as declaring a 
machine name that already exists. 

ODH 

13 

Unknown: Classification does not exist or is 
inappropriate. 

Actions 

Hexadecimal 

Decimal 


Code 

Code 

Description 

01 H 

1 

Retry: Retry a few times, then prompt user to 
determine if the program should continue or be 
terminated. 

02H 

2 

Delay Retry: Retry several times after pause, then 
prompt user to determine if the program should 
continue or be terminated. 

OSH 

3 

User: If the input was entered by a user, advise 
reentry. The error, however, may have occurred in the 
program itself, such as a bad drive letter or bad 
filename specification. 

04H 

4 

Abort: Abort application with cleanup. The application 
cannot proceed, but the system is in an orderly state 
and it is safe to stop the application. 

OSH 

5 

Immediate Exit: Stop application immediately without 
clearing registers. Do not use the application to close 
files or update indexes, but exit as soon as possible. 

06H 

6 

Ignore: Ignore. 

07H 

7 

Retry After User Intervention: The user needs to 
perform some action such as removing a diskette and 
inserting a different one. Then retry the operation. 
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Locus (Location) 


Hexadecimal 

Decimal 


Value 

Value 

Description 

01 H 

1 

Unknown; Not specific; not appropriate. 

02H 

2 

Block Device: Related to random access mass disk 
storage. 

03H 

3 

Net: Related to the network. 

04H 

4 

Serial Device: Related to serial devices. 

OSH 

5 

Memory: Related to random access memory. 
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OOH — Program Terminate 


Purpose 

Stops the execution of a program. 


Examples 

MOV AH, OOH ; Function Call - Terminate Program 

INT 21H ; Issue request to DOS 

; No return 

Comments 

The terminate, Ctri-Break, and criticai error exit addresses are restored to 
the vaiues they had on entry to the terminating program, from the vaiues 
saved in the program segment prefix. Aii fiie buffers are fiushed and the 
handies opened by the process are ciosed. Any fiies that have changed in 
iength and not ciosed are not recorded properiy in the directory. Controi 
transfers to the terminate address. This caii performs exactiy the same 
function as interrupt 20H. It is the program's responsibiiity to ensure that the 
CS register contains the segment address of its program segment prefix 
controi biock before cailing this function. 

Function 4CH — Terminate a Process is the preferred method for ending a 
program. 
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01 H — Console Input with Echo 


Purpose 

Waits for a character to be read at the standard input device (uniess one is 
ready), then echoes the character to the standard output device and returns 
the character in AL. 


Examples 


MOV 

INT 

MOV 

CMP 

JNE 

MOV 

INT 

MOV 

Normal Char: 


AH,01H 

21H 

Char,AL 

AL,0 

Normal _Char 

AH,01H 

21H 

ExtChar,AL 


Function Call - keyboard input 
Issue request to DOS 
Save character 
Extended character ? 

No! 

Function Call - keyboard input 
Issue request to DOS 
Save extended character 


Character LABEL WORD ; Complete character 

Char DB ? ; Character buffer 

ExtChar DB ? ; Character buffer 

Comments 

The character is checked for a Ctri-Break. if Ctri-Break is detected, an 
interrupt 23H is executed. 

For function caii 01 H, extended ASCII codes require two function caiis. The 
first cail returns OOH as an indicator that the next caii wiil return an extended 
code. 
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02H — Display Output 


Purpose 

Outputs the character in DL to the standard output device. 


Examples 



MOV 

AH,02H 

; Function Call - Display Output 

MOV 

DLjChar 

; Get character to display 

INT 

21H 

; Issue request to DOS 

CHAR 

DB ? 

; Character buffer 


Comments 

If the character in DL is a backspace (08), the cursor is moved ieft one 
position (nondestructive). If a Ctrl-Break is detected after the output, an 
interrupt 23H is executed. 
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OSH — Auxiliary Input 


Purpose 

Waits for a character from the standard auxiliary device, then returns that 
character in AL. 

Examples 


MOV 

AH, OSH 

; Function Call - Auxiliary Input 

INT 

21H 

; Issue request to DOS 

MOV 

Char,AL 

; Save character 

DB 

7 

; Character buffer 


Comments 

Auxiliary (AUX) suppert is unbuffered and noninterrupt driven. 

At startup, PC DOS 7 initializes the first auxiliary port to 2400 baud, no parity, 
one-stop bit, and 8-bit word. 

The auxiliary function calls (OSH and 04H) do not return status or error codes. 
For greater contrel, yeu should use the ROM BIOS reutine (interrupt 14H) or 
write an AUX device driver and use lOCtl. 
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04H — Auxiliary Output 


Purpose 

Examples 


Comments 


Outputs the character in DL to the standard auxiliary device. 


MOV 

AH,04H 

; Function Call - Auxiliary Output 

MOV 

DLjChar 

; Get character to output 

INT 

21H 

; Issue request to DOS 



; Nothing returned 

DB 

7 

; Character buffer 


If the character in DL is a backspace (08), the cursor is moved left one 
position (nondestructive). If a Ctrl-Break is detected after the output, an 
interrupt 23H is executed. 
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OSH — Printer Output 


Purpose 

Outputs the character in DL to the standard printer device. 

Examples 


MOV 

AH, OSH 

; Function Call - Printer Output 

MOV 

DLjChar 

; Get character to output 

INT 

21H 

; Issue request to DOS 



; Nothing returned 

DB 

7 

; Character buffer 
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06H — Direct Console I/O 


Purpose 

Gets a character from the standard input device if one is ready, or outputs a 
character to the standard output device. 

Examples 


In_l oop: 

MOV 

AH,06H 

Function Call - Direct Console I/O 

MOV 

DL,-1 

OFFH for input 

INT 

2IH 

Issue request to DOS 

JZ 

Injoop 

No character yet on input 

MOV 

Char,AL 

Save character 

CMP 

AL,0 

Extended Character ? 

ONE 

Normal Char 

No! 

MOV 

AH,07H 

Function Call - Keyboard Input 

INT 

2IH 

Issue request to DOS 

MOV 

ExtChar, AL 

Save extended character 

Normal_Char: 


or 

MOV 

AH,06H 

Function Call - Direct Console I/O 

MOV 

DLjChar 

Output character to display (not OFFH) 

INT 

2IH 

Issue request to DOS 

Character 

LABEL WORD 

Complete character 

Char 

DB ? 

Character buffer 

ExtChar 

DB ? 

Character buffer 


Comments 

If DL is FFH, AL returns with the 0 fiag ciear and an input character from the 
standard input device, if one is ready. If a character is not ready, the 0 flag 
will be set. 

If DL is not FFFI, DL is assumed to have a valid character that is output to the 
standard output device. This function does not check for Ctrl-Break, or 
Ctrl-PrtSc. 

For function call 06FI, extended ASCII codes require two function calls. The 
first call returns OOFI as an indicator that the next call will return an extended 
code. 
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07H — Direct Console Input Without Echo 


Purpose 

Waits for a character to be read at the standard input device (uniess one is 
ready), then returns the character in AL. 


Examples 


MOV 

AH,07H 

INT 

2IH 

MOV 

Char,AL 

CMP 

AL,0 

JNE 

Normal Char 

MOV 

AH,07H 

INT 

21H 

MOV 

ExtChar, AL 

Normal 

Char: 


Character LABEL 

Char DB 

ExtChar DB 


Function Call - Direct Console Input (no echo) 
Issue request to DOS 
Save character 
Extended character ? 

No! 

Function Call - Direct Console Input (no echo) 
Issue request to DOS 
Save extended character 


WORD ; Complete character 

? ; Character buffer 

? ; Character buffer 


Comments 

As with function caii 06H, no checks are made on the character. 

For function caii 07H, extended ASCII codes require two function calis. The 
first caii returns OOH as an indicator that the next caii wili return an extended 
code. 
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OSH — Console Input Without Echo 


Purpose 

Waits for a character to be read at the standard input device (uniess one is 
ready) and returns the character in AL. 

Examples 


MOV 

AH, OSH 


Function Cal 1 

- Console 

INT 

21H 


Issue request 

to DOS 

MOV 

Char,AL 


Save character 

CMP 

AL,0 


Extended character ? 

JNE 

Normal 

Char 

No! 


MOV 

AH, OSH 


Function Cal 1 

- Console 

INT 

21H 


Issue request 

to DOS 

MOV 

ExtChar, AL 

Save extended 

character 

Norma 

_Char: 




Character 

LABEL WORD ; 

Compl ete 

Char 


DB 

? 

• 9 

Character 

ExtChar 

DB 

? 

• 9 

Character 


Comments 

The character is checked for Ctri-Break. If Ctri-Break is detected, an 
interrupt 23H is executed. 

For function cali OSH, extended ASCII codes require two function calis. The 
first cail returns OOH as an indicator that the next caii wili return an extended 
code. 


150 


PC DOS 7 



09H — Display String 


Purpose 

Sends the characters in the string to the standard output device. 

Examples 

MOV AX,SEG String 

MOV DS,AX ;Set DS:DX to string 

MOV DX, OFFSET String 

MOV AH,09H ; Function Call - Display String 

INT 21H ; Issue request to DOS 


String DB "This string ends at the first Dollar" 

DB 0DH,0AH 

DB "$" 

Comments 

The character string in memory must be terminated by a $ (24H). Each 
character in the string is output to the standard output device in the same 
form as function caii 02H. 

ASCIi codes ODH and OAH represent carriage return and line feed, 
respectively. 
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OAH — Buffered Keyboard Input 


Purpose 

Reads characters from the standard input device and piaces them in the 
buffer beginning at the third byte. 

Examples 


MOV 

AX,SEG Buffer 


MOV 

DS,AX 

;Set DS:DX to return Buffer 

MOV 

DX, OFFSET Buffer 


MOV 

AH, OAH 

; Function Cal 1 -Buffered 
; Keyboard Input 

INT 

21H 

; Issue request to DOS 


Buffer 

DB 

128 

; Max length of input 

CurLen 

DB 

7 

; Number of characters input 




; (excludes Return (ODH)) 

CurText 

DB 

128 DUP(?) 

; Up to 128 characters allowed 


Comments 

The first byte of the input buffer specifies the number of characters the buffer 
can hoid. This vaiue cannot be 0. Reading the standard input device and 
fiiling the buffer continues untii Enter is read. If the buffer filis to one iess 
than the maximum number of characters it can hold, each additional 
character read is ignored and causes the bell to ring, until Enter is read. The 
second byte of the buffer is set to the number of characters received, 
excluding the carriage return (ODH), which is always the last character. 
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OBH — Check Standard Input Status 


Purpose 

Examples 


Comments 


Checks if there is a character avaiiabie from the standard input device. 


In_L00P: 

MOV AH, OBH ; Function Call - Check Input 

INT 21H ; Issue request to DOS 

CMP AL,-1 ; OFFH indicates character available 

JNE In LOOP 


If a character is avaiiabie from the STDIN device, AL is FFH. Otherwise, AL 
is undefined. If a Ctrl-Break is detected, an interrupt 23FI is executed. 
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OCH — Clear Keyboard Buffer and Invoke a Keyboard Function 


Purpose 

Clears the standard input device of any characters, then executes the 
function call number in AL. 


Examples 


MOV 

AH, OCH 

; Function Call - Clear keyboard & 

; Invoke function 

MOV 

AL, Function 

; Function Call to execute 

; (only OlH, 06H, 07H, OSH, and OAH are allowed) 

INT 

21H 

; Issue request to DOS 


Output depends on Function Call selected 
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ODH — Disk Reset 


Purpose 


Examples 


Comments 


Writes to the disk file buffers that have been modified. All buffers are then 
made available for reuse. 


MOV AH, ODH ; Function Call - Disk Reset 

INT 21H ; Issue request to DOS 

; No return 


It is necessary to close or commit all open files to correctly update the disk 
directory. 
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OEH — Select Disk 


Purpose 

Selects the drive specified in DL (0=A, 1=B, etc.) (if valid) as the default 
drive. 


Examples 


MOV 

AH, OEH 

MOV 

DL,Dri ve 

INT 

2IH 

MOV 

LastDri ve,AL 

MOV 

AH,I9H 

INT 

21H 

CMP 

AL,DL 

ONE 

Error 


Function Call - Select Disk 

Drive to select (0=A:, 1=B:, ...) 

Issue request to DOS 

Save max drive number (1=A:, 2=B:, ...) 

Function Call - Get Current Disk 

Issue request to DOS 

Selected drive = requested 

No, Error! 


Drive DB ; New Drive to select 

LastDrive DB ; Highest Valid Drive 


Comments 

The total number of unique drive letters, including diskette and hard disk 
drives, that can be referenced is returned in AL. The value in AL is equal to 
the value of LASTDRIVE in CONFIG.SYS or the tetal number of installed 
devices, whichever is greater. For PC DOS 7 5 is the minimum value 
returned in AL. If the system has only one diskette drive, it is ceunted as twe 
to be consistent with the philosophy of thinking of the system as having 
legical drives A and B. 
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OFH — Open File 


Purpose 

Searches the current directory for the named file and AL returns FFH if it is 
not found. If the named file is found, AL returns OOH and the FCB is filled as 
described below. 

Examples 


MOV 

AX,SEG FCB 

; Address FCB Parameter Block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH, OFH 

; Function Call -FCB Open 

INT 

21H 

; Issue request to DOS 


FCB 

LABEL 

BYTE 


Dri ve 

DB 

0 

; Drive (0=Current, I=A, 2=B, . 

FName 

DB 

"FILENAME" 

; File Name (blank padded) 

Ext 

DB 

I — 
X 

LU 

; File Extension (blank padded) 


DB 

25 DUP(O) 

; Filled in by PC DOS 7 


Comments 

AL is OOH if the file is opened. 

AL is FFH if the file was not opened. 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. 

If the drive code was 0 (default drive), it is changed to the actual drive used 
(1=A, 2 = B, and so on). This allows changing the default drive without 
interfering with subsequent operations on this file. The current block field 
(FCB bytes C-D) is set to 0. The size of the record to be worked with (FCB 
bytes E-F) is set to the system default of 80H. The size of the file and the 
date are set in the FCB from information obtained from the directory. You 
can change the default value for the record size (FCB bytes E-F) or set the 
random record size and/or current record field. Perform these actions after 
the open, but before any disk operations. 

The file is opened in compatibility mode. For information on compatibility 
mode, refer to function call SDH. 
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10H — Close File 


Purpose 

Closes a file. 


Examples 


MOV 

AX,SEG FCB 

; Address FCB Parameter Block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,10H 

; Function Call -FCB Close 

INT 

21H 

; Issue request to DOS 

CMP 

AL,0 

; File Closed? 

JNE 

Error 

; No, Error! 

FCB 

LABEL 

BYTE 


; Contents set by previous operations 


Comments 


AL is OOH if the file is elesed. 

AL is FFH if the file was not closed. 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. 

This function call must be executed on open files after file writes, and we 
highly recommend that it be used en all files. If the file is not found in its 
correct position in the current directery, it is assumed the disk was changed 
and AL returns FFFI. Otherwise, the directory is updated to reflect the status 
in the FCB, the buffers for that file are flushed, and AL returns OOH. 
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11 H — Search for First Entry 


Purpose 

Searches the current directory for the first matching fiiename. 


Examples 


MOV AXjSEG DTA ; Address Buffer for found file 
MOV DS,AX ; information 

MOV DX, OFFSET DTA 

MOV AHjlAH ; Function Call -Set DTA address 

INT 21H ; Issue request to DOS 

MOV AXjSEG FCB ; Address FCB parameter block 

MOV DS,AX 

MOV DX, OFFSET FCB 

MOV AHjllH ; Function Call -FCB search first 

INT 21H ; Issue request to DOS 

CMP AL,0 ; File found? 

ONE Error ; No, Error! 


FCB 

LABEL 

BYTE 



Fdri ve 

DB 

0 

; Drive (0=Current, I=A, 2=B, . 

..) 

Fname 

DB 

"FILENAME" 

; File name (blank padded. 

may use ? 

Fext 

DB 

1 — 
X 

LU 

; File extension (blank padded. 

may use ? 


DB 

25 DUP(O) 

; Filled in by DOS 


DTA 

LABEL 

BYTE 



Ddri ve 

DB 

7 

; Drive 


Dname 

DB 

"77?77?77" 

; File Name (blank padded) 


Dext 

DB 


; File Extension (blank padded) 



DB 

25 DUP(O) 

; Filled in by PC DOS 7 



Comments 

AL is OOH if the fiie is found. 

AL is FFH if the fiie was not found. 

Use Function Gail 59FI (Get Extended Error) to determine the actuai error 
condition. 

The current disk directory is searched for the first matching fiiename. If ncne 
is found, AL returns FFH. Giobai fiiename characters are aiicwed in the 


Appendix B. PC DOS 7 Function Calls 159 



filename and extension. If a matching filename is found, AL returns OOH and 
the locations at the disk transfer address are set as follows: 


• If the FCB provided for searohing was an extended FCB, the first byte at 
the disk transfer address is set to FFFI followed by 5 bytes of 0, then the 
attribute byte from the search FCB, then the drive number used (1=A, 
2=B, etc.), then the 32 bytes of the directory entry. Thus, the disk 
transfer address contains a valid unopened extended FCB with the same 
search attributes as the search FCB. 

• If the FCB provided for searching was a standard FCB, then the first byte 
is set to the drive number used (1=A, 2=B), and the next 32 bytes 
contain the matching directory entry. Thus, the disk transfer address 
contains a valid unopened normal FCB. 

Note: If an extended FCB is used, the following search pattern is used: 

1. If the attribute is 0, only normal file entries are found. Entries for 
volume label, sub-directories, hidden and system files, are not 
returned. 

2. If the attribute field is set for hidden or system files, or directory 
entries, it is an inclusive search. All normal file entries, plus all 
entries matching the specified attributes, are returned. To look at 
all directory entries except the volume label, the attribute byte 
may be set to hidden + system + directory (all 3 bits on). 

3. If the attribute field is set for the volume label, it is considered an 
exclusive search, and only the volume label entry is returned. 
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12H — Search for Next Entry 


Purpose 

Searches the current directory for the next matching fiiename. 


Examples 


MOV 

AX,SEG DTA ; 

Address Buffer for found file 

MOV 

DS,AX ; 

Information 

MOV 

DX, OFFSET DTA 


MOV 

AH,1AH ; 

Function Call -Set DTA address 

INT 

21H ; 

Issue request to DOS 

MOV 

AX,SEG FCB ; 

Address FCB Parameter Block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,12H ; 

Function Call -FCB Search Next 

INT 

21H ; 

Issue request to DOS 

CMP 

AL,0 ; 

File found? 

ONE 

Error ; 

No, Error! 

FCB 

LABEL BYTE 



; As set by FCB Search First 


DTA 

LABEL 

BYTE 



Dri ve 

DB 

? 

; Drive 


Fname 

DB 

"77777777" 

; File Name 

(blank padded) 

Ext 

DB 


; File Extension (blank padded) 


DB 

25 DUP(O) 

; Filled in 

by PC DOS 7 


Comments 

AL is OOH if the fiie is found. AL is FFH if the fiie was not found. Use 
Function Gail 59Fi (Get Extended Error) to determine the actuai error 
condition. 

After a matching fiiename has been found using function caii 11H, function 
12H may be cailed to find the next match to an ambiguous request. 

The DTA contains information from the previous Search First or Search Next. 
Ali of the FCB, except for the name/extension fieid, is used to keep 
information necessary for continuing the search, so no disk operations may 
be performed if this FCB is between a previous function 11H or 12Fi cali and 
this one. 
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13H — Delete File 


Purpose 

Deletes all current directory entries that match the specified filename. The 
specified filename cannot be read-only. 


Examples 


MOV 

AX,SEG FCB 

; Address FCB Parameter Block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,13H 

; Function Call -FCB Delete File 

INT 

21H 

; Issue request to DOS 

CMP 

AL,0 

;File(s) Deleted? 

JNE 

Error 

;No, Error! 


FCB 

LABEL 

BYTE 




Dri ve 

DB 

0 

; Drive 



FName 

DB 

Filename 

; File Name 

(blank padded, 

may use ? 

Ext 

DB 

Ext 

; File Extension (blank padded, 

may use ? 


DB 

25 DUP(O) 

; Filled in 

by DOS 



Comments 

AL Is OOH If the file Is found. 

AL Is FFH If the file was not found. 

Use Function Call 59FI (Get Extended Error) to determine the actual error 
condition. 

All matching current directory entries are deleted. The global filename 
character “?” Is allowed in the filename or extension. If no directory entries 
match, AL returns FFFI; otherwise AL returns OOFI. 

If the file Is specified In read-only mode, the file Is not deleted. 

Note: Close open files before deleting them. 

Network Access Rights: Requires Create access rights. 
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14H — Sequential Read 


Purpose 

Loads the record addressed by the current block (FCB bytes C-D) and the 
current record (FCB byte 1 F) at the disk transfer address (DTA), then the 
record address is increased. 


Examples 


MOV 

AX,SEG DTA 


;Address Data buffer 

MOV 

DS,AX 



MOV 

DX, OFFSET DTA 



MOV 

AH,1AH 


; Function call Set DTA Address 

INT 

21H 


; Issue request to DOS 

MOV 

AX,SEG FCB 


; Address FCB Parameter Block 

MOV 

DS,AX 



MOV 

DX, OFFSET FCB 



MOV 

AH,14H 


; Function Call -FCB Sequential 

INT 

21H 


; Issue request to DOS 

CMP 

AL,0 


;Data Read? 

JNE 

Error 


;No, Error! 

FCB 

LABEL 

BYTE 


; Set by previous open 


DTA 

LABEL 

BYTE 



DB 

?Dup(0) ;I/0 buffer 


Comments 


AL is OOH if the read was successful. 

AL is 01 H if the file was at End of File (EOF). 

AL is 02H if the read would have caused a wrap or overflow because the DTA 
was too small (the read was not completed). 

AL is OSH if EOF (a partial record was read and filled out with Os). 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. The length of the record is determined by the FCB record size 
field. 

Network Access Rights: Requires Read access rights. 
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15H — Sequential Write 


Purpose 

Writes the record addressed by the current block and record fields (size 
determined by the FCB record size field) from the disk transfer address. If 
records are less than the sector size, the record is buffered for an eventual 
write when a sector's worth of data is accumulated. Then the record 
address is increased. 

Examples 


MOV 

AX,SEG DTA 

;Address Data buffer 

MOV 

DS,AX 


MOV 

DX, OFFSET DTA 


MOV 

AH,1AH 

; Function Set DTA Address 

INT 

21H 

; Issue request to DOS 

MOV 

AX,SEG FCB 

; Address FCB Parameter Block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,15H 

; Function Call -FCB Sequential Write 

INT 

21H 

; Issue request to DOS 

CMP 

AL,0 

;Data Written? 

JNE 

Error 

;No, Error! 


FCB LABEL BYTE 

; Set by previous open 
DTA LABEL BYTE 

DB ?Dup(0) ;I/0 buffer 

Comments 


AL is OOH if the write was successful. 

AL is 01 H if the disk or diskette is full (write cancelled). 

AL is 02H if the write would have caused a wrap or overflow because the 
DTA was too small (write cancelled). 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. If the file is specified in read-only mode, the sequential write is 
not performed and 01 H is returned in AL. 

Network Access Rights: Requires Write access rights. 
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16H — Create File 


Purpose 

Creates a new file. 

Examples 


MOV 

MOV 

MOV 

AX,SEG FCB 
DS,AX 

DX, OFFSET FCB 

; Address FCB parameter block 

MOV 

AH,16H 

; Function Call -FCB create file 

INT 

21H 

; Issue request to DOS 

CMP 

AL,0 

;File created and opened? 

ONE 

Error 

;No, Error! 


FCB 

LABEL 

BYTE 


Fdri ve 

DB 

0 

; Drive (0=Current, 1=A, 2=B, . 

Fname 

DB 

"FILENAME" 

; File name (blank padded) 

Fext 

DB 

"EXT" 

; File extension (blank padded) 


DB 

25 DUP(O) 

; Filled in by DOS 


Comments 

AL is OOH if the file is created and opened. 

AL is FFH if the file was not created (normally a full direotory or disk full). 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. 

If a matching entry is found it is reused. If no match is found, the directory is 
searched for an empty entry. If a match is found, the entry is initialized to a 
0-length file, the file is opened (see function call OFH), and AL returns OOH. 

The file may be marked hidden during its creation by using an extended FCB 
oontaining the appropriate attribute byte. 

Network Access Rights: Requires Create access rights. 
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17H — Rename File 


Purpose 

Changes every matching occurrence of the first fiiename in the current 
directory of the specified drive to the second, with the restriction that two 
fiies cannot have the same name and extension. 

Examples 


MOV 

AX,SEG FCB 

; Address FCB Parameter Block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,17H 

; Function Call -FCB Rename File 

INT 

21H 

; Issue request to DOS 

CMP 

AL,0 

;File(s) Renamed? 

ONE 

Error 

;No, Error! 


FCB 

LABEL 

BYTE 






Fdri ve 

DB 

0 

Drive (0=Current, 

1=A, 2=B, ...) 




Fname 

DB 

"FILENAME" 

File Name 

(blank padded, 

may 

use 

7 

Fext 

DB 

"EXT" 

File Extension 

(blank padded, 

may 

use 

7 


DB 

5 DUP(O) 

Reserved 





NewName 

DB 

"FILENAME" 

New File Name 

(blank padded. 

may 

use 

7 

NewExt 

DB 

"EXT" 

New File Extension 

(blank padded. 

may 

use 

7 


DB 

7 DUP(O) 

Reserved 






Comments 

AL is OOH if the fiie or fiies were renamed. 

AL is FFH if a fiie in the current directory did not match or the new name 
aiready exists. 

Use Function Gail 59FI (Get Extended Error) to determine the actuai error 
condition. The modified FCB has a drive code and fiiename in the usuai 
position, and a second fiiename on the sixth byte after the first (DS:DX+11FI) 
in what is normaiiy a reserved area. 

If “?”s appear in the second name, the corresponding positions in the 
originai name are unchanged. 

If the file is specified in read-only mode, the file is not renamed. 

Network Access Rights: Requires Create access rights. 
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19H — Current Disk 


Purpose 

Returns the current default drive. 


Examples 

MOV 

AH,19H 

; Function Call - Get Current Disk 


INT 

21H 

; Issue request to DOS 


MOV 

Di skjAL 

; Save Current Disk 


Disk DB 

7 

; Current Disk code (0=A:, 1=B:, . 


Comments 

AL returns with the code of the current default drive {0=A, 1=B, and ethers). 


Appendix B. PC DOS 7 Function Calls 167 



1AH — Set Disk Transfer Address 


Purpose 





Sets 

the disk transfer address to DS:DX. 

Examples 

MOV 

AX,SEG DTA 

;Address Buffer 


MOV 

DS,AX 



MOV 

DX, OFFSET DTA 



MOV 

AH,1AH 

; Function Call -Set DTA address 


INT 

21H 

; Issue request to DOS 


DTA 

LABEL BYTE 

; Data Buffer 


Comments 

The area defined by this caii is from the address in DS:DX to the end of the 
segment in DS. PC DOS 7 does not aiiow disk transfers to wrap around 
within the segment, or overfiow into the next segment. If you do not set the 
DTA, the defauit DTA is offset 80H in the program segment prefix. To get the 
DTA, issue function caii 2FH. 
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1BH — Allocation Table Information 


Purpose 

Returns information about the ailocation tabie for the defauit drive. 


Examples 


MOV AH,1BH 
INT 21H 

MOV NumAllocUnits,DX 
MOV NumSectsAllocUnitjAL 
MOV SectSize,CX 


Function Call - Allocation Table 

Information 

Issue request to DOS 

Save Number of Allocation Units 

Save Number of Sectors/Allocation Unit 

Save of Sector Size 


MOV WORD PTR Medi aType@+0, BX 


Save Pointer to Media Type Byte 


MOV WORD PTR MediaType@+2,DS 


NumAllocUnits DW ? 
NumSectsAl locUni t DB ? 
SectSize DW ? 
MediaTypeO DO ? 


Number of Allocation Units on Current Drive 
Number Sectors in an Allocation Unit 
Sector Size 

Pointer to Media Type byte 


Comments 

Refer to function caii 36H (Get Disk Free Space). 
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1CH — Allocation Table Information for Specific Device 
Purpose 

Returns allocation table information for a specific device. 


Examples 


MOV AH,1CH 
MOV DL, Drive 
INT 21H 

MOV NumAllocUnits,DX 

MOV NumSectsAllocUnitjAL 

MOV SectSize,CX 

MOV WORD PTR MediaType@+0,BX 

MOV WORD PTR MediaType@+2,DS 


Dri ve DB 

NumAllocUnits DW ? 

NumSectsAl locUni t DB ? 

SectSize DW ? 

MediaTypeO DO ? 


Function Call - 
Allocation Table Information 
Drive requested (0=current, 

1=A:, ...) 

Issue request to DOS 

Save Number of Allocation Units 

Save Number of Sectors/Allocation Unit 

Save of Sector Size 

Save Pointer to Media Type Byte 


drive number to get info for 
Number of Allocation Units 
on specified drive 
Number Sectors in an 
Allocation Unit 
Sector Size 

Pointer to Media Type byte 


Comments 

This call is the same as call 1BH, except that on entry DL contains the 
number of the drive that contains the needed information (0 = default, 1 = 
A, and so forth). For more information on PC DOS 7 disk allocation, refer to 
“The Disk Directory” on page 11. Also, refer to function call 36H (Get Disk 
Free Space). 


170 PC DOS 7 



1FH — Get Default Drive Parameter Block 
Purpose 

Retrieves the drive parameter bleck for the default drive. 

Examples 


MOV 

AH,1FH 

; Function 

Cal 1 - Get Defaul t DPB 

INT 

21H 

; Issue request to DOS 

CMP 

AL,0FFH 

9 


JZ 

Error 

9 


MOV 

WORD PTR [DEFAULT DPB] ,BX 

MOV 

WORD PTR [DEFAULT_DPB+2] ,DS 

’B STRUCT 




dpbOri ve 

DB 

7 

Drive Number (0=A, 1=B...) 

dpbUni t 

DB 

7 

Unit Number for Driver 

dpbSectorSize 

DW 

7 

Sector Size in Bytes 

dpbCl usterMask 

DB 

7 

Sectors per Cluster 

dpbCl usterShift DB 

7 

Sectors per Cluster - power of 2 

dpbFi rstFAT 

DW 

7 

First Sector Containing FAT 

dpbFATCount 

DB 

7 

Number of FATs 

dpbRootEntries 

DW 

7 

Number of Root Directory Entries 

dpbFi rstSector 

DW 

7 

First Sector of First Cluster 

dpbMaxCl uster 

DW 

7 

Number of Clusters on Drive + 1 

dpbFATSize 

DW 

7 

Number of Sectors Occupied by FAT 

dpbOi rSector 

DW 

7 

First Sector of Directory 

dpbOri verAddr 

DD 

7 

Address of the Device Driver 

dpbMedi a 

DB 

7 

Media Descriptor Byte 

dpbFi rstAccess 

DB 

7 

Indicates Access to the Drive 

dpbNextOPB 

DD 

7 

Address of Next Drive Parameter Block 

dpbNextFree 

DW 

7 

Last Allocated Cluster 

dpbFreeCnt 

DW 

7 

Count of Free Clusters 


DPB 

Comments 

If AL contains zero then DS:BX (segment/offset registers) point to the DPB 
structure that will contain the drive parameters. If the default drive Is for 
some reason invalid or a disk error occurs then AL will contain OFFH. 
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21 H — Random Read 


Purpose 

Reads the record addressed by the current block and current record fields 
Into memory at the current disk transfer address. 


Examples 


MOV AX,SEG DTA 

MOV DS,AX 

MOV DX, OFFSET DTA 

MOV AH,1AH 

INT 21H 

MOV AX,SEG FCB 

MOV DS,AX 

MOV DX, OFFSET FCB 

MOV AH,21H 

INT 21H 

CMP AL,0 

JNE Error 


FCB LABEL BYTE 

; Set by previous open 
; DTA label byte 


;Set up FCB 
;Address Data buffer 


; Function Set DTA Address 
; Issue request to DOS 
; Address FCB Parameter Block 


; Function Call -FCB Random Read 
; Issue request to DOS 
;Data Read? 

;No, Error! 


Comments 


AL Is OOH If the read was successful. 

AL Is 01 H If the file was at End of File (EOF) (no data read). 

AL Is 02H If the read would have caused a wrap or overflow because the DTA 
was too small (the read was not completed). 

AL Is OSH If EOF (a partial record was read and filled out with O's). 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. The current block and current record fields are set to agree with 
the random record field. The record addressed by these fields Is read Into 
memory at the current disk transfer address. For Information on record size 
see Chapter 4, “Accessing Files Using File Control Blocks” on page 23. 

Note: Function 24H must be called before using this function. 

Network Access Rights: Requires Read access rights. 
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22H — Random Write 


Purpose 

Writes the record addressed by the current block and current record fields 
from the current disk transfer address. 

Examples 


;Set 

up FCB 


MOV 

AX,SEG FCB 

; Address FCB parameter block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,24H 

; Function Call-FCB Set 
; Relative record field 

INT 

2IH 

; Issue request to DOS 

MOV 

AX,SEG DTA 

;Address data buffer 

MOV 

DS,AX 


MOV 

DX, OFFSET DTA 


MOV 

AH,1AH 

; Function Set DTA address 

INT 

2IH 

; Issue request to DOS 

MOV 

AX,SEG FCB 

; Address FCB parameter block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,22H 

; Function Call-FCB random writers 

INT 

2IH 

; Issue request to DOS 

CMP 

AL,0 

;Data written? 

JNE 

Error 

;No, error! 

FCB 

LABEL 

BYTE 

; Set by previous open 

DTA 

LABEL 

BYTE 


Comments 

AL is OOH if the write was successful. 

AL is 01 H if the write or diskette is full (write cancelled). 

AL is 02H if the read would have caused a wrap or overflow because the DTA 
was too small (write cancelled). 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. 
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The current block and current record fields are set to agree with the random 
record field. Then the record addressed by these fields is written (or in the 
case of records not the same as sector sizes — buffered) from the disk 
transfer address. 

If the file is specified in read-only mode, the random write is not performed. 
Network Access Rights: Requires Write access rights. 
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23H — File Size 


Purpose 

Searches the current directory for an entry that matches the specified fiie 
and sets the FCBs random record fieid to the number ef records in the fiie. 


Examples 


MOV 

MOV 

MOV 

AX,SEG FCB 
DS,AX 

DX, OFFSET FCB 

; Address FCB parameter block 

MOV 

AH,23H 

; Function Call -FCB file size 

INT 

21H 

; Issue request to DOS 

CMP 

AL,0 

; File found? 

JNE 

Error 

; No, error! 


FCB 

LABEL 

BYTE 


Dri ve 

DB 

0 

; Drive (0=Current, 1=A, 2=B, . 

Name 

DB 

"FILENAME" 

; File name (blank padded) 

Ext 

DB 

I — 
X 

LU 

; File extension (blank padded) 


DB 

25 DUP(O) 

; Filled in by DOS 


Comments 

AL is OOH if the fiie exists. 

AL is FFH if the fiie was not created (normaliy a fuil directory or disk fuil). 

Use Function Gail 59Fi (Get Extended Error) to determine the actuai error 
condition. 

The directory is searched for the matching entry. If a matching entry is 
found, the randem record fieid is set to the number of records in the fiie (in 
terms of the record size fieid rounded up). If no matching entry is found, AL 
returns FFFI. 

Note: If you do not set the FCB record size fieid before using this function, 
incorrect information is returned. 
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24H — Set Relative Record Field 


Purpose 

Sets the random record field to the same file address as the current block 
and record fields. 


Examples 

MOV 

AX,SEG FCB 

; Address FCB parameter block 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 


MOV 

AH,24H 

; Function Call-FCB set 

INT 

21H 

; Relative record field 
; Issue request to DOS 


FCB LABEL BYTE 

; Set by previous open 


Comments 


You must call this function before you perform random reads and writes, and 
random block reads and writes. 
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25H — Set Interrupt Vector 


Purpose 

Sets the interrupt vector table for the interrupt number. 


Examples 


MOV 

AXjSEG Handler 

; Address new handler 

MOV 

DS,AX 


MOV 

DX, OFFSET Handler 


MOV 

AH,25H 

; Function Call - Set Interrupt 
; Vector 

MOV 

AL, Vector 


INT 

21H 

; Issue request to DOS 


Vector DB 
Handler: 


; Number of vector to be replaced 
;Code to process interrupt 


Comments 


The interrupt vector table for the interrupt number specified in AL is set to 
address contained in DS:DX. Use function call 35H (Get Interrupt Vector) to 
obtain the contents of the interrupt vector. 
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26H — Create New Program Segment 


Purpose 

Creates a new program segment. 


Examples 

MOV 

AH,26H 


; Function Call - Create Program 
; Segment 


MOV 

DX,SEG PSP 


; Segment address to create new PSP 


INT 

21H 


; Issue request to DOS 


PSP 

LABEL 

BYTE 

; Area to f i 11 in 



DB 

lOOH DUP(O) 


Comments 

The entire 100H area at location 0 in the current program segment is copied 
into location 0 in the new program segment. The memory size information at 
location 6 in the new segment is updated and the current termination, 
Ctrl-Break exit and critical error addresses from Interrupt vector table entries 
for Interrupts 22H, 23H, and 24H are saved In the new program segment 
starting at OAH. They are restored from this area when the program ends. 

Note: The EXEC function call 4BH provides a more complete service. 

Therefore, you should use the EXEC 4BH and avoid using this call. 
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27H — Random Block Read 


Purpose 

Reads the specified number of records (in terms of the record size fieid) from 
the fiie address specified by the random record fieid into the disk transfer 
address. 


Examples 


MOV 

AX,SEG DTA 

MOV 

DS,AX 

MOV 

DX, OFFSET DTA 

MOV 

AH,IAH 

INT 

2IH 

MOV 

AX,SEG FCB 

MOV 

DS,AX 

MOV 

DX, OFFSET FCB 

MOV 

AH,24H 

INT 

2IH 

MOV 

AX,SEG FCB 

MOV 

DS,AX 

MOV 

DX, OFFSET FCB 

MOV 

CX, Records to read 

MOV 

AH,27H 

INT 

2IH 

CMP 

AL,0 

ONE 

Error 


;Set up disk transfer address 
;Address data buffer 


; Function set DTA address 
; Issue request to DOS 

; Address FOB parameter block 


; Function Call - FCB Set 
; Relative Record Field 
; Issue request to DOS 
; Address FCB parameter block 


; number of records to read 
; Function Call - FCB random block read 
; Issue request to DOS 
;Data read? 

;No, error! 


FCB LABEL BYTE 

; Set by previous open 
DTA LABEL BYTE 

DB ?Dup(0) ;I/0 buffer 

Records to read DW 
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Comments 


AL is OOH if the read was successfui. 

AL is 01 H if the fiie was at End of Fiie (EOF) (no data read). 

AL is 02H if the read wouid have caused a wrap or overflow because the DTA 
was too small (the read was not completed). 

AL is OSH if EOF (a partial record was read and filled out with zeros). 

Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. 

The random record field and the current block/record fields are set to 
address the next record (the first record not read). 

Note: Function 24H must be called before using this function. 

Network Access Rights: Requires Read access rights. 
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28H — Random Block Write 


Purpose 

Writes the specified number of records from the disk transfer address into 
the fiie address specified by the random record fieid. 


Examples 


MOV 

AX,SEG 

DTA 

MOV 

DS,AX 


MOV 

DX, OFFSET DTA 

MOV 

AH,1AH 


INT 

21H 


MOV 

AX,SEG 

FCB 

MOV 

DS,AX 


MOV 

DX, OFFSET FCB 

MOV 

AH,24H 


INT 

2IH 



MOV 

AX,SEG FCB 

MOV 

DS,AX 

MOV 

DX, OFFSET FCB 

MOV 

CX, Records to write 

MOV 

AH,28H 

INT 

2IH 

CMP 

AL,0 

ONE 

Error 


DTA LABEL BYTE 

DB ?DUP(0) 


;Set up disk transfer address 
;Address data buffer 


; Function set DTA address 
; Issue request to DOS 

; Address FOB parameter block 


; Function Call-FCB set 
; Relative record field 
; Issue request to DOS 


; Address FOB parameter block 


; Number of records to write 
; Function Call - FCB Random Block write 
; Issue request to DOS 
;Data written? 

;No, error! 


; I/O Buffer 


Comments 


AL is OOH if the write was successfui. 

AL is 01 H if the disk or diskette is fuii (write canceiied). 

AL is 02H if the write wouid have caused a wrap or overfiow because the 
DTA was too smaii (write canceiied). 
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Use Function Call 59H (Get Extended Error) to determine the actual error 
condition. 

If there Is Insufficient space on the disk, AL returns 01 H and no records are 
written. If CX is 0 upon entry, no records are written, but the file is set to the 
length specified by the random record field, whether longer or shorter than 
the current file size. (Allocation units are released or allocated as 
appropriate.) 

Note: Function call 24FI must be called before using this function. 

Network Access Rights: Requires Write access rights. 
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29H — Parse Filename 


Purpose 

Parses the specified fiiename. 


Examples 


MOV 

AX,SEG CmdBuf 


MOV 

DS,AX 

;Address command string 

MOV 

SI, OFFSET CmdBuf 

MOV 

AX,SEG FCB 


MOV 

ES,AX 

; Address FCB Parameter Block 

MOV 

DI, OFFSET FCB 


MOV 

AH,29H 

; Function Call - FCB Parse Filename 

MOV 

AL, OPTIONS 

;Set desired action 

INT 

2IH 

; Issue request to DOS 

CMP 

AL,-I 

; Drive valid? 

JE 

Error 

;No, Error! 

CmdBuf LABEL 

BYTE 


DB 

" a:file.ext ",0DH 

FCB 

LABEL 

BYTE 

; Created in a pre-open state based on input found. 


Options DB ? ; parsing options 

Comments 


The contents of AL are used to determine the action to take, as shown beiow: 


< m u St = 0 > 

bit: 7 6 5 4 3 2 1 0 

If bit 0 = 1, ieading separators are scanned off the command iine at DS:SI. 
Otherwise, no scan-off of ieading separators takes piace. 

If bit 1 =1, the drive ID byte in the FOB wiii be set (changed) only if a drive 
was specified in the command iine being parsed. 

If bit 2 = 1, the fiiename in the FOB wiil be changed oniy if the command iine 
contains a filename. 

If bit 3 = 1 , the fiiename extension in the FOB wili be changed oniy if the 
command iine contains a fiiename extension. 


Appendix B. PC DOS 7 Function Calls 183 



Filename separators include the following characters: 


+ along with TAB and SPACE. Filename terminators include all of 
these characters plus ,<, >, |, /, ", [, ], and any control characters. 

Output: 

AL is OOH if no global characters (? or *) were found in the Command String. 
AL is 01 H if global characters (? or *) were found in the Command String. 

AL is FFH if the drive specified is invalid. 

The command line is parsed for a filename of the form d'Jilename.ext, and if 
found, a corresponding unopened FCB is created at ES:DI. If no drive 
specifier is present, it is assumed to be all blanks. If the character * appears 
in the filename or extension, it and all remaining characters in the name or 
extension are set to ?. 

DS:SI returns pointing to the first character after the filename and ES:DI 
points to the first byte of the formatted FCB. If no valid filename is present, 
ES:DI + 1 contains a blank. 


184 PC DOS 7 



2AH — Get Date 


Purpose 

Returns the day of the week, the year, menth and date. 

Examples 



MOV 

AH,2AH 

Function Call - Get Date 


INT 

21H 

Issue request to DOS 


MOV 

DayofWeekjAL 

Save Day of the Week 


MOV 

Year,CX 

Save Year 


MOV 

Month, DH 

Save Month 


MOV 

Day,DL 

Save Day 

DayofWeek 

DB ? 

0=Sunday, ... 6=Saturday 

Year 


DW ? 

1980 to 2099 

Month 


DB ? 

1 to 12 

Day 


DB ? 

1 to 31 


Comments 


If the time-of-day clock rolls over te the next day, the date is adjusted 
accordingly, taking into account the number ef days in each month and leap 
years. 
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2BH — Set Date 


Purpose 

Sets the date (also sets CMOS clock, If present). 

Examples 



MOV 

AH,2BH 

Function Cal 1 - Set 


MOV 

CX,Year 

Set Year 


MOV 

DH, Month 

Set Month 


MOV 

DL,Day 

Set Day 


INT 

21H 

Issue request to DOS 


CMP 

AL,0 

Valid Date? 


JNE 

Error 

No! 

Year 


DW ? 

1980 to 2099 

Month 


DB ? 

1 to 12 

Day 


DB ? 

1 to 31 


Comments 

AL Is OOH If the date Is valid and the operation Is successful. 

AL Is FFH If the date Is not valid. 

On entry, CX:DX must have a valid date In the same format as returned by 
function call 2AH. 

On return, AL returns OOH If the date Is valid and the set operation is 
successful. AL returns FFH if the date is not valid. 
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2CH — Get Time 


Purpose 

Returns the time; hours, minutes, seconds and hundredths of seconds. 


Examples 


MOV 

AH,2CH 

Function Call - 
Get Time 

INT 

21H 

Issue request to DOS 

MOV 

Hour,CH 

Save 

Hour 

MOV 

Mi nute, CL 

Save 

Mi nute 

MOV 

Second, DH 

Save 

Second 

MOV 

Hundredth, DL 

Save 

Partial Second 

Hour 

DB ? 

0 to 

23 

Mi nute 

DB ? 

0 to 

59 

Second 

DB ? 

0 to 

59 

Hundredth 

DB ? 

0 to 

99 


Comments 

On entry, AH centains 2CH. On return, CX:DX contains the time-of-day. Time 
is actualiy represented as four 8-bit binary quantities as foiiews: 

CH Hours (0-23) 

CL Minutes (0-5 9) 

DH Seconds (0-5 9) 

DL 1/100 seconds (0-99). 

This format is readiiy converted to a printabie form yet can aiso be used fer 
caicuiations, such as subtracting one time vaiue from another. 
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2DH — Set Time 


Purpose 

Sets the time (also sets the CMOS clock, if present). 

Examples 


MOV 

AH,2DH 

Function Cal 1 - Set 

MOV 

CHjHour 

Set Hour 

MOV 

CL, Mi nute 

Set Mi nute 

MOV 

DH, Second 

Set Second 

MOV 

DL, Hundredth 

Set Partial Second 

INT 

21H 

Issue request to DOS 

CMP 

AL,0 

Valid Time? 

ONE 

Error 

No! 

Hour 

DB ? 

0 to 23 

Mi nute 

DB ? 

0 to 59 

Second 

DB ? 

0 to 59 

Hundredth 

DB ? 

0 to 99 


Comments 

AL is OOH if the time is valid. 

AL is FFH if the time is not valid. 

On entry, CX:DX has time in the same format as returned by function 2CFI. 
On return, if any component of the time is not valid, the set operation is 
cancelled and AL returns FFFI. If the time is valid, AL returns OOFI. 

If your system has a CMOS realtime clock, it will be set. 
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2EH — Set/Reset Verify Switch 


Purpose 





Sets the verify switch. 


Examples 

; To set 

VERIFY=0FF 



MOV 

AH,2EH 

Function Cal 1 - Set 
VERIFY 


MOV 

AL,0 

Set OFF 


INT 

21H 

Issue request to DOS 


; To set 

VERIFY=0N 



MOV 

AH,2EH 

Function Cal 1 - Set 
VERIFY 


MOV 

AL,1 

Set ON 


INT 

21H 

Issue request to DOS 


Comments 

On entry, AL must contain 01 H to turn verify on, or OOH to turn verify off. 
When verify is on, PC DOS 7 performs a verify operation each time it 
performs a disk write to assure proper data recording. Aithough disk 
recording errors are very rare, this function has been provided for 
appiications in which you may wish to verify the proper recording of criticai 
data. You can obtain the current setting of the verify switch through function 
caii 54H. 

Note: Verification is not supported on data written to a network disk. 
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2FH — Get Disk Transfer Address (DTA) 


Purpose 

Returns the current disk transfer address. 

Examples 


MOV 

AH,2FH 

; Function Cal 1 - Get 
; DTA Address 

INT 

21H 

; Issue request to DOS 

MOV 

WORD PTR DTA0+O,BX 

; Save Address 

MOV 

WORD PTR DTA@+2,ES 



DO ? 

; DTA Buffer 


Comments 

On entry, AH contains 2FH. On return, ES:BX contains the current Disk 
Transfer Address. You can set the DTA using function caii 1AH. 
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30H — Get DOS Version Number 


Purpose 

Returns the DOS versien number. 

Examples 


PUSH 

CX 

CX destroyed in call 

PUSH 

BX 


MOV 

AH,30H 

Function Call - Get PC DOS 7 
Version 

INT 

21H 

Issue request to DOS 

MOV 

MajorVersion,AL 

Save Version 

MOV 

MinorVersion, AH 


MOV 

DOS Running Froni,BH 


POP 

BX 


POP 

CX 



MajorVersion DB 

MinorVersion DB 

DOS_Running_Froni DB 
DOS_Running_Froni DB 

Comments 

On entry, AH contains 30H. On return, CX is set to 0. AL contains the major 
version number. AH contains the minor version number. BH contains 8 or 0 
for DOS running or not running in ROM. 

If AL returns a major version number of 0, you can assume that the DOS 
version is pre-DOS 2.00. 

Use function call 33H AL=6 (Get or Set System Value) to get the true version 
number. 


A U I A • I I 

YY of X.YY 

0 = DOS not running in ROM 
8 = DOS running in ROM 
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31H — Terminate Process and Remain Resident 


Purpose 

Terminates the current process and attempts to set the initial allocatien block 
to the memory size in paragraphs. 


Examples 

MOV 

AH,31H 

Function Call - Terminate 


MOV 

AL, RetCode 

and Keep Process 

Set value of ERRORLEVEL 


MOV 

DX,MySize 

Set my program and data size 


INT 

21H 

Issue request to DOS 


INT 

20H 

Be safe if on DOS Version l.X 


RetCode 

DB ? 

Value to return to my EXEC' er 


My Size 

DW ? 

Size of my code and data 




(in paragraphs) 


Comments 

On entry, AL centains a binary return code. DX contains the memory size 
value in paragraphs. This function call does not free up any other allocation 
blocks belonging to that process. Files opened by the process are not closed 
when the call is executed. The return cede passed in AL is retrievable by 
the parent through Wait (function call 4DH) and can be tested through the 
ERRORLEVEL batch subcommands. 

Memory is used efficiently if the block containing a copy of the environment 
is deallocated before terminating. This can be done by loading ES with the 
segment contained in 2C of the PSP, and issuing function call 49H (Free 
Allocated Memory). The five standard handles, 0000 through 0004, should be 
closed before exiting. 
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32H — Get Drive Parameter Block 
Purpose 

Retrieves the drive parameter bleck for the specified drive. 

Examples 


MOV 

DL, DRIVE 

NUM 

Drive Number (0=Default, I=A, 2=B...) 

MOV 

AH,32H 


Function Call - Get DPB 

INT 

21H 


Issue request to DOS 

CMP 

AL,0FFH 

9 



JZ 

Error 

9 



MOV 

WORD PTR [SPECIFIED DPB],BX 

MOV 

WORD PTR [SPECIFIED_DPB+2] ,DS 

’B STRUCT 





dpbOri ve 

DB 

7 


Drive Number (0=A, 1=B...) 

dpbUni t 

DB 

7 


Unit Number for Driver 

dpbSectorSize 

DW 

7 


Sector Size in Bytes 

dpbCl usterMask 

DB 

7 


Sectors per Cluster 

dpbCl usterShift DB 

7 


Sectors per Cluster - power of 2 

dpbFi rstFAT 

DW 

7 


First Sector Containing FAT 

dpbFATCount 

DB 

7 


Number of FATs 

dpbRootEntries 

DW 

7 


Number of Root Directory Entries 

dpbFi rstSector DW 

7 


First Sector of First Cluster 

dpbMaxCl uster 

DW 

7 


Number of Clusters on Drive + 1 

dpbFATSize 

DW 

7 


Number of Sectors Occupied by FAT 

dpbOi rSector 

DW 

7 


First Sector of Directory 

dpbOri verAddr 

DD 

7 


Address of the Device Driver 

dpbMedi a 

DB 

7 


Media Descriptor Byte 

dpbFi rstAccess 

DB 

7 


Indicates Access to the Drive 

dpbNextOPB 

DD 

7 


Address of Next Drive Parameter B1 

dpbNextFree 

DW 

7 


Last Allocated Cluster 

dpbFreeCnt 

DW 

7 


Count of Free Clusters 


DPB 
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Comments 


If AL contains zero then DS:BX {segment/offset registers) point to the DPB 
structure that wiii contain the drive parameters. If the specified drive is for 
some reason invaiid or a disk error occurs then AL wili contain OFFH. 
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33H — Get or Set System Value 


Purpose 

Examples 


Set or get the state of System Values such as BREAK (Ctrl-Break checking). 


To 

check BREAK state 



MOV 

AH,33H 

Function Call - Get/Set 
System value 


MOV 

AL,0 

Do Get BREAK 


INT 

2IH 

Issue request to DOS 


MOV 

BREAK, DL 

Save state (00=0FF, 0IH=0N) 

To 

set BREAK=0FF 



MOV 

AH,33H 

Function Call - Get/Set 
System value 


MOV 

AL,I 

Do Set BREAK 


MOV 

DL,0 

Set OFF 


INT 

21H 

Issue request to DOS 

To 

set BREAK=0N 



MOV 

AH,33H 

Function Call - Get/Set 
System Value 


MOV 

AL,I 

Do Set BREAK 


MOV 

DL,I 

Set ON 


INT 

21H 

Issue request to DOS 

To 

get the 

Boot Dri ve 



MOV 

AH,33H 

Function Call - Get/Set 
System Value 


MOV 

AL,5 

Do Get Boot Drive 


INT 

2IH 

Issue request to DOS 


MOV 

Dri ve,DL 

Save boot drive 

To 

get the 

True Version Number 


MOV 

AH,33H 

Function Call - Get/Set 
System Value 


MOV 

AL,6 

Get True Version 


INT 

2IH 

Issue request to DOS 


MOV 

MajorVersion,BL 
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MOV MinorVersiorijBH 


MOV 

Rev 

Level ,DL 


MOV 

DOS] 

>lags,DH 


BREAK 

DB 

7 

Current BREAK state (0=0FF, 1=0N) 

Dri ve 

DB 

7 

PC DOS 7 boot drive (1=A, 2=B, ... 

MajorVersion 

DB 

7 

True Version X of X.YY 

MinorVersion 

DB 

7 

YY of X.YY 

Rev_Level 

DB 

7 

The lower three bits indicates the 
revision number. All other bits 
are reserved and set to 0. 

D0S_F1 ags 

DB 

7 

Bits 0-2 Reserved. 

Bit 3 When set to 1, DOS is 

running from ROM. 

Bit 4 When set to 1, DOS is 

running from HMA. 

Bits 5-7 Reserved. 
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34H — Get In DOS Flag Address 


Purpose 


Examples 


Comments 


Returns the address of the PC DOS 7 InDOS flag. The InDOS flag shows the 
current state of Interrupt 21 H processing. 


MOV 

INT 

AH,34H 

21H 

; Function Call - Get InDOS Flag Address 
; Issue request to DOS 

MOV 

InDOS, BYTE 

1 1 

X 

CD 

OO 

LU 

1— 

Q_ 


While PC DOS 7 is processing one of the Interrupt 21 H functions, the value of 
the InDOS flag will be nonzero. 

The ES:BX (segment/offset) register pair will contain the InDOS flag address. 
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35H — Get Interrupt Vector 


Purpose 

Examples 


Comments 


To obtain the address in an interrupt vector. 


MOV AH,35H 

MOV AL, Vector 
INT 21H 

MOV WORD PTR 01dVect+0,BX 
MOV WORD PTR 01dVect+2,ES 


Function Call - 
Set Interrupt Vector 
Vector to get (0 to 255) 
Issue request to DOS 


OldVect DO 

Vector DB 


; Previous vector contents 
; Vector number to get 


On return, ES:BX contains the CS:iP interrupt vector for the specified 
interrupt. Use function cali 25H (Set Interrupt Vector) to set the interrupt 
vectors. 
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36H — Get Disk Free Space 


Purpose 

Returns the disk free space (available clusters, clusters/drive, bytes/sector). 


Examples 


MOV 

AH,36H 

Function Call - 
Get disk free space 

MOV 

DLjDri ve 

Drive to query 
(0=current, 1=A:, 
2=B:, ...) 

INT 

21H 

Issue request to DOS 

CMP 

AX,-1 

Error? 

JE 

Error 

Yes 

MOV 

SectAU, AX 

Save allocation unit 
Size 

MOV 

Avail AU,BX 

Save free allocation 
Uni ts 

MOV 

SectSize, CX 

Save sector size 

MOV 

Total AU,DX 

Save disk size 

MOV 

AX, SectSize 

Calculate allocation 



Unit size 

MUL 

SectAU 


MOV 

CX,AX 

CX = bytes/AU 

MOV 

AX, Total AU 

Calculate total space 

MUL 

CX 


MOV 

WORD PTR TotalBytes+0,AX 

Save it 

MOV 

WORD PTR Total Bytes+2,DX 


MOV 

AX, AvailAU 

Calculate free space 

MUL 

CX 


MOV 

WORD PTR FreeBytes+0,AX 

Save it 

MOV 

WORD PTR FreeBytes+2,DX 



SectAU DW ? 

AvailAU DW ? 
SectSize DW ? 
Total AU DW ? 

Total Bytes DD ? 
FreeBytes DD ? 
Dri ve DD ? 


Sectors in an 

Allocation unit 

Free allocation units 

Bytes in a sector 

Number of allocation 

Uni ts on DL di sk 

Disk size in bytes 

Free space in bytes 

Drive number to get info for 
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Comments 


If the drive number in DL was valid, BX contains the number of available 
allocation units, DX contains the total number of allocation units on the drive, 
CX contains the number of bytes per sector, and AX contains the number of 
sectors for each allocation unit. 
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38H — Get or Set Country Dependent Information 


Purpose 

Sets the Active Country or returns country dependent information. 

Examples 


; To set the Current Country 


MOV 

AH,38H 

Function Call - Get/Set 

Country Information 

MOV 

AL, CountrylD 

Country ID (-1 if >= 255) 

MOV 

BX, CountryIDX 

Country ID (if AL=-I) 

MOV 

DX,-1 

Indicate set country code 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

; To get Country Information 


MOV 

AX,SEG Buffer 


MOV 

DS,AX 


MOV 

DX, OFFSET Buffer 


MOV 

AH,38H 


MOV 

AL, CountrylD 

Country ID (-1 if >= 255) 

(0 to get current country) 

MOV 

BX, CountryIDX 

Country ID (if AL=-I) 

INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

CountryCode, BX 

Save current Country Code 

CountryCode 

DW ? 

Current country code 

CountryIDX 

DW ? 

Extended country code for i nput 

Buffer 

LABEL WORD 

Country information (see format below) 

CountrylD 

DB ? 

Country code for i nput 
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Country Information 


DateFormat 

DW 

7 

$Symbol 

DB 

"????", 0 

SeplOOO 

DB 

"?",0 

Sepl 

DB 

"?",0 

SepDate 

DB 

"?",0 

SepTime 

DB 

"?",0 

$ Format 

DB 

7 


SigDigits 

DB 

7 

TimeFormat 

DB 

7 

UpperCaseALO 

DD 

7 

SepData 

DB 

"?",0 

Reserved 

DW 

5 DUP 


Date Format: 

0 = m d y order 

1 = d m y order 

2 = y m d order 
Currency Symbol 

example: "DM",0,?,? 

Thousands Separator 
example: " ,0 
Fractions Separator 
example: ".",0 
Date Separator 
example: '7",0 
Time Separator 
example: ":",0 
Currency Format: 

0 = currency symbol, value 

1 = value, currency symbol 

2 = currency symbol, space, value 

3 = value, space, currency symbol 

4 = currency symbol is decimal separator 
Number of Significant Digits in Currency 
Time Format: 

0 = 12 hour clock 

1 = 24 hour clock 

Address of Routine to Upper Case AL 
Only for values >=80H 
Data List Separator 
example: " ,0 
Reserved for future 


Comments 

The date format has the following values and meaning: 

Code Date 
0 = USA m d y 
1=Europe d m y 
2=Japan y m d 

Case Map Call Address: The register contents for the case map call are: 


On 

Register 

Entry 

Contents 

AL 

ASCII code of character to be converted to uppercase 
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On 

Register 

Return 

Contents 

AL 

ASCII code of the uppercase Input character 


The case map call address Is In a form suitable for a FAR call Indirect. 


Results 

Error codes are returned In AX. Issue function call 59H (Get Extended Error) 
for additional Information about the error class, suggested action, and 
location. Function Call 65FI (Get Extended Country Information) returns more 
country Information and is preferred. 

Setting the Current County Code by using this function call Is not 
recommended. The user can set It by placing a COUNTRY command in the 
CONFIG.SYS file. The Country Code set by the user should not be changed. 
The NLSFUNC PC DOS 7 extension must be installed to change the Current 
Country. 
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39H — Create Subdirectory (MKDIR) 


Purpose 

Examples 


Comments 


Creates the specified directory. 


MOV 

MOV 

AX,SEG 

DS,AX 

DName 

; Directory Name 

MOV 

DX, OFFSET 

DName 


MOV 

AH,39H 


; Function-Make a directory 

INT 

JC 

21H 

Error 


; Issue request to DOS 


DName DB "?? .. ??",0 ; ASCIIZ Name 

; Example: 

; "c:\dir",0 


On entry, DS:DX contains the address of an ASCilZ string with drive and 
directory path names. Ali directory ieveis other than the iast one in the 
name must exist before using this function. Oniy one directory ievei at a 
time can be created with this function. The maximum iength of the ASCliZ 
string is 64 characters. 

Error codes are returned in AX. Issue function caii 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. 

Network Access Rights: Requires Create access rights. 
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3AH — Remove Subdirectory (RMDIR) 


Purpose 

Removes the specified directory. 


Examples 

MOV 

AX,SEG DName 

; Directory name 

MOV 

DS,AX 


MOV 

DX, OFFSET DName 


MOV 

AH,3AH 

; Function-Remove directory 

INT 

21H 

; Issue request to DOS 

JC 

Error 



DName DB "?? .. ??",0 ; ASCIIZ Name 

; example: "c:\dir",0 


Comments 

On entry, DS:DX contains the address of an ASCilZ string with the drive and 
directory path names. The specified directory is removed from the structure. 
The current directory or a directory with fiies in it cannot be removed. 

Error codes are returned in AX. Issue function caii 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. 

Network Access Rights: Requires Create access rights. 
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3BH — Change the Current Directory (CHDIR) 


Purpose 

Changes the current directory to the specified directory. 


Examples 

MOV 

AX,SEG DName 

; Directory name 

MOV 

DS,AX 


MOV 

DX, OFFSET DName 


MOV 

AH,3BH 

; Function - Change directory 

INT 

21H 

; Issue request to DOS 

JC 

Error 



DName DB "?? .. ??",0 ; ASCIIZ Name 

; example: "c:\dir",0 


Comments 

On entry, DS:DX contains the address of an ASCIIZ string with drive and 
directory path names. The string is limited to 64 characters and cannot 
contain a network path. If any member of the directory path does not exist, 
the directory path Is not changed. Otherwise, the current directory is set to 
the ASCIIZ string. 

Error codes are returned In AX. Issue function call 59H (Get Extended Error) 
for additional Information about the error class, suggested action, and 
location. 
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3CH — Create a File 


Purpose 


Examples 


Comments 


Creates a new 

file or shortens an 

old file to 0 length in preparation for 

writing. 




MOV 

AX,SEG FName 

;File name 

MOV 

DS,AX 



MOV 

DX, OFFSET FName 



MOV 

AH,3CH 


Function - Create a File 

MOV 

CX, Attribute 


Attribute of the file 

Allowed values 




0001H=Read only 

0002H=Hidden 

0004H=System 

0008H=Volume label 

INT 

21H 


Issue request to DOS 

JC 

Error 


Error code in AX 

MOV 

Handle, AX 


Save file handle for 

FName 

HR "99 99 

",0 

ASCIIZ Name 




example: "c:\dir\file. ext", 0 

Handle 

DW ? 


File handle 

Attribute 

DW ? 


Attributes for directory entry 


If the file did not exist, the file is created in the appropriate directory and the 
file is given the read/write access code. The file is opened for read/write, 
the read/write pointer is set to the first byte of the file and the handle is 
returned in AX. Note that function call 43H (Change File Mode) can be used 
later to change the attribute of the file. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. 

This function does not replace an existing volume label. You must delete the 
existing volume label before issuing this call. 

Network Access Rights: Requires Create access rights. 
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SDH — Open a File 


Purpose 

Opens the specified fiie. 


Examples 


MOV 

AX,SEG FName 

MOV 

DS,AX 

MOV 

DX, OFFSET FName 

MOV 

AH, SDH 

MOV 

ALjOpenMode 

INT 

21H 

JC 

Error 

MOV 

Handle, AX 


File name 


Function - Open a File 

Issue request to DOS 
Error code in AX 

Save file handle for following operations 


FName 

DB 

"?? 

??",0 

; ASCIIZ Name 
; example: 

Handle 

DW 

7 


; File Handle 

OpenMode 

DB 

7 


; Open mode 


c:\dir\file.ext",0 


Comments 

The read/write pointer is set at the first byte of the fiie and the record size of 
the fiie is 1 byte. The read/write pointer can be changed with function caii 
42H. The returned fiie handie must be used for subsequent input and output 
to the fiie. The fiie's date and time can be obtained or set through caii 57H, 
and its attribute can be obtained through caii 43H. 

Error codes are returned in AX. Issue functicn caii 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. 


Notes: 

1. This caii opens any normai or hidden fiie whose name matches the name 
specified. 

2. Device names cannot end in a coion. 

3. When a file is ciosed, any sharing restrictions piaced on it by the open 
are canceied. 

4. Fiie sharing must be icaded, or the fiie must be a network fiie for the 
sharing modes to function. Refer to the SHARE command. 
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5. The file read-only attribute can be set when creating the file using 
extended FCBs or specifying the appropriate attribute in CX and using 
the CHMOD interrupt 21 H function call or the PC DOS 7 ATTRIB 
command. 

6. If the file is inherited by the subordinate process, all sharing and access 
restrictions are also inherited. 

7. If an open file handle is duplicated by either of the DUP function calls, all 
sharing and access restrictions are also duplicated. 

Open Mode 

The open mode is defined in AL and consists of four bit-oriented fields: 

Inheritance flag Specifies if the opened file is inherited by a 
subordinate process. 

Sharing mode field Defines which operations other processes can perform 
on the file. 

Reserved field 

Access field Defines which operations the current process can 

perform on the file. 

Bit Fields 

The bit fields are mapped as follows: 

<I> < S > <R> < A > 

Open Mode bi ts 76543210 

I Inheritance flag 

If I = 0; File is inherited by subordinate processes. 

If I = 1 ; File is private to the current process. 

S Sharing Mode 

The file is opened as follows: 

S = 000 — Compatibility mode 
S = 001 — DenyRead/Write mode (exclusive) 

S = 010 — DenyWrite mode 
S = oil — DenyRead mode 
S = 100 — DenyNone mode 

Any other combinatiens are invalid. 

When opening a file, you must inform PC DOS 7 which operations 
any other processes, in sharing mode, can perform on the file. 
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The default, compatibility mode, denies all other computers in a 
network access to the file. If other processes can continue to read 
the file while your process is operating on it, specify DenyWrite. 
DenyWrite prohibits writing by other processes, but allows reading. 

Similarly, you must specify which operations, or access modes, your 
process can perform. The default access mode, ReadWrite, causes 
the open request to fail if another process on the computer or any 
other computer on a network has the file opened with any sharing 
mode other than DenyNone. If you intend to read from the file only, 
your Open will succeed unless all other processes have specified 
DenyNone or DenyWrite. File sharing requires cooperation of both 
sharing processes. 

R Reserved (set this bit field to 0). 

A Access 

The file access is assigned as follows: 

If A = 000; Read access 
If A = 001; Write access 
If A = 010; Read/Write access 

Any other combinations are invalid. 

Network Access Rights: If the Access field (A) of the Open mode field (AL) is 
equal to: 

000 Requires Read access rights 

001 Requires Write access rights 

010 Requires Read/Write access rights 

Compatibility Mode 

A file is considered to be in compatibility mode if the file is opened by: 

• Any of the CREATE function calls 

• An FCB function call 

• A handle function call with compatibility mode specified. 

A file can be opened any number of times in compatibility mode by a single 
process, provided that the file is not currently open under one of the other 
four sharing modes. If the file is marked read-only, and is open in DenyWrite 
sharing mode with Read Access, the file may be opened in Compatibility 
Mode with Read Access. If the file was successfully opened in one of the 
other sharing modes and an attempt is made to open the file again in 
Compatibility Mode, an interrupt 24FI is generated to signal this error. The 
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base interrupt 24H error indicates Drive not ready, and the extended error 
indicates a Sharing violation. 

Sharing Modes 

The sharing medes for a fiie opened in compatibiiity mode are changed by 
PC DOS 7 depending en the read-oniy attribute of the fiie. This aiiows 
sharing of read-oniy fiies. 


File Opened By 

Read-Only 

Access 

Sharing Mode 

FCB 

Read-Only 

DenyWrite 

Handle Read 

Read-Only 

DenyWrite 

Handle Write 

Error 


Handle Read or Write 

Error 



File Opened By 

Not Read-Only 

Access 

Sharing Mode 

FCB 

Read/Write 

Compatibility 

Handle Read 

Read 

Compatibility 

Handle Write 

Write 

Compatibility 

Handle Read or Write 

Read or Write 

Compatibility 


DenyRead/Write Mode (Exclusive) 

If a fiie is successfuliy opened in DenyRead/Write mede, access te the fiie is 
exciusive. A fiie currently open in this mede cannot be opened again in any 
sharing mode by any process (inciuding the current process) untii the file is 
ciosed. 

DenyWrite Mode 

A fiie successfuiiy opened in DenyWrite sharing mode prevents any other 
write access epens to the fiie (A = 001 or 010) untii the fiie is ciosed. An 
attempt to open a fiie in DenyWrite mode is unsuccessfui if the fiie is open 
with a write access. 

DenyRead Mode 

A fiie successfuiiy opened in DenyRead sharing mode prevents any other 
read sharing access opens to the fiie (A = 000 er 010) untii the fiie is ciesed. 
An attempt to open a fiie in DenyRead sharing mode is unsuccessfui if the 
fiie is open in Compatibiiity mode or with a read access. 
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DenyNone Mode 


A file successfully opened in DenyNone mode places ne restrictiens on the 
read/write accessibility of the file. An attempt to open a file in DenyNone 
mede is unsuccessful if the file is epen in Cempatibility mede. 

When accessing files that reside on a network disk, no local buffering is done 
when files are opened in any of the fellowing sharing modes: 

• DenyRead 

• DenyNone. 

Therefore, in a network environment, DenyRead/Write sharing mede, 
Cempatibility sharing mode, and DenyWrite mode opens are buffered locally. 
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The following sharing matrix shows the resuits of opening, and subsequentiy 
attempting to reopen the same file using aii combinations of access and 
sharing modes: 



DRW 

DW 

DR 

ALL 

I 

10 

0 

I 

10 

0 

I 

10 

0 

I 

10 

0 

D 

R 
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I 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

10 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

0 
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N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

D 

W 

I 

N 

N 

N 

Y 
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N 

N 

N 

N 

Y 

N 

N 

10 

N 

N 

N 

N 

N 

N 

N 

N 

N 

Y 

N 

N 
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N 

N 

N 

N 

N 

N 

Y 

N 

N 

Y 

N 

N 

D 

R 

I 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

Y 

10 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

N 

Y 
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N 

N 

N 

N 

N 

N 

N 

N 

Y 

N 

N 

Y 

A 

L 

L 

I 

N 

N 

N 

Y 

Y 

Y 

N 

N 

N 

Y 

Y 

Y 

10 

N 

N 

N 

N 

N 

N 

N 

N 

N 

Y 

Y 

Y 

0 

N 

N 

N 

N 

N 

N 

Y 

Y 

Y 

Y 

Y 

Y 


Y :2nd,3rd, . . .open is allowed 

N :2nd,3rd, . . .open is denied 

DRW :DenyRead/Wri te Mode (Exclusive) 
DW :DenyWrite Mode 

DR :DenyRead Mode 

ALL : Read/Write Mode 

I :Read Only Access 

0 :Write Only Access 

10 : Read/Write Access 
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3EH — Close a File Handle 


Purpose 

Examples 


Comments 


Closes the specified file handle. 


MOV 

AH,3EH 

; Function Call - 
; Close a Handle 

MOV 

BX, Handle 


INT 

21H 

; Issue request to DOS 

JC 

Error 

; Error code in AX 


Handle DW ? ; File Handle (from Open / Create) 


On entry, BX contains the file handle that was returned by Open or Create. 
On return, the file is closed, the directory is updated, and all internal buffers 
for that file are flushed. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. 
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3FH — Read from a File or Device 


Purpose 

Transfers the specified number of bytes from a fiie into a buffer iocation. 


Examples 

MDV 

AX,SEG Buffer 

Address data buffer 

MDV 

DS,AX 


MDV 

DX,DFFSET Buffer 


MDV 

AH,3FH 

Function - Read from 

MDV 

BX, Handle 


MDV 

CX,BufSize 

Buffer size 

INT 

21H 

Issue request to DDS 

JC 

Error 

Error code in AX 

CMP 

AX,D 

At End Df File? 

JE 

EDF 

Yes! 

MDV 

SizeRead,AX 

Save Amount Read 


N 

EDU 

512 

Handle 

DW 

7 

BufSize 

DW 

N 

Buffer 

DB 

N DUP(? 

Si zeRead 

DW 

7 


Typical buffer size 
File Handle (from Open /Create) 
Buffer Size, N is 
Data Buffer 

Amount of Data in Buffer 


Comments 

On entry, BX contains the fiie handie. CX contains the number of bytes to 
read. DS:DX contains the buffer address. On return, AX contains the 
number of bytes read. 

This function cail attempts to transfer (CX) bytes from a file into a buffer 
location. It is not guaranteed that all bytes will be read. For example, when 
PC DOS 7 reads from the keyboard, at most one line of text is transferred. If 
this read is performed from the standard input device, the input can be 
redirected. If the value in AX is D, then the program has tried to read from 
the end of file. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested acticn, and 
location. 

Network Access Rights: Requires Read access rights. 
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40H — Write to a File or Device 


Purpose 

Transfers the specified number of bytes from a buffer intc a specified fiie. 


Examples 

MOV AX,SEG Buffer 
MOV DS,AX 

MOV DX, OFFSET Buffer 
MOV CX,BufSize 
MOV AH,40H 
MOV BX, Handle 
MOV DX, OFFSET Buffer 
INT 21H 
JC Error 
CMP AX,CX 
JB Full Disk 


;Data Buffer 


; Function-Write to a File 


Issue request to DOS 
Error code in AX 
Disk Full? 

Yes! 


N 

EQU 

512 

; Typical buffer size 

Handle 

DW 

7 

; File Handle (from Open / Create) 

BufSize 

DW 

N 

; Buffer Size 

Buffer 

DB 

N DUP(?) 

; Data Buffer 


Comments 

On entry, BX contains the fiie handie. CX contains the number cf bytes to 
write. DS:DX contains the address of the data to write. 

This function cail attempts to transfer (CX) bytes from a buffer into a fiie. AX 
returns the number of bytes actuaily written, if the carry fiag is net set and 
this vaiue is not the same as the number requested (in CX), it sheuid be 
considered an error. Aithough no error code is returned, your program can 
compare these vaiues. Normaliy, the reason for the error is a fuli disk. If 
this write is performed to the standard eutput device, the output can be 
redirected. 

To truncate a fiie at the current position of the fiie pointer, set the number of 
bytes (CX) to 0 before issuing the interrupt 21 H. The fiie pointer can be 
moved tc the desired position by reading, writing, and perferming function 
caii 42H, (Move Fiie Read/Write Pointer.) 

If the file is read-only, the write tc the fiie or device is not performed. 
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Error codes are returned in AX. Issue function caii 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. 

Network Access Rights: Requires Write access rights. 
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41 H — Delete a File from a Specified Directory (UNLINK) 
Purpose 

Removes a directory entry associated with a filename. 


Examples 


MOV 

AX,SEG FName 

; File Name 

MOV 

OS, AX 


MOV 

OX, OFFSET FName 


MOV 

AH,41H 

; Function-Delete a File 

INT 

21H 

; Issue request to DOS 

JC 

Error 

; Error code in AX 


FName DB "?? .. ??",0 ; ASCIIZ Name 

; example: "c:\dir\File. ext", 0 

Comments 

Global filename characters are not allowed In any part of the ASCIIZ string. 
Read-only files cannot be deleted by this call. To delete a read-only file, you 
can first use call 43H to change the file's read-only attribute to 0, then delete 
the file. 

Error codes are returned In AX. Issue function call 59H (Get Extended Error) 
for additional Information about the error class, suggested action, and 
location. 

Network Access Rights: Requires Create access rights. 
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42H — Move File Read/Write Pointer (LSEEK) 


Purpose 

Moves the read/write peinter according to the method specified. 


Examples 


MOV 

AH,42H 

Function Call - 
Move Read/Write Pointer 

MOV 

AL, Method 

Method of Positioning: 

0 = From Beginning of File 

(BOF) 

1 = From Current Position 

2 = From End of File (EOF) 

MOV 

BX, Handle 

Select File 

MOV 

DX,W0RD PTR Position+0 

New Position = Position + METHOD 

MOV 

CX,W0RD PTR Position+2 


INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

WORD PTR Position+0, AX 

Set new File Position 

MOV 

WORD PTR Position+2,DX 


Handle 

DW ? 

File Handle (from Open / 

Create) 

Posi ti on 

DO ? 

File Offset (may be 
negati ve) 

Method 

DB ? 



Comments 

On entry, AL contains a method value. BX contains the file handle. CX:DX 
contains the desired offset In bytes with CX containing the most significant 
part. On return, DX:AX centains the new location of the peinter with DX 
containing the most significant part if the carry flag Is net set. 

Error codes are returned In AX. Issue functlen call 59H (Get Extended Errer) 
for additional Information about the error class, suggested action, and 
location. 

This function call moves the read/write pointer according to the following 
methods: 
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AL 

Description 

0 

The pointer is moved CX:DX bytes (offset) from the beginning of fhe file. 

1 

The poinfer is moved to the current iocation plus offset. 

2 

The pointer is moved to the end-of-fiie plus offset. This method can be 
used to determine file's size. 


Note: If an LSEEK operation is performed on a file that resides on a network 
disk that is open in either DenyRead or DenyNone sharing mode, the 
read/write pointer information is adjusted on the computer where the 
file actually exists. If the file is opened in any other sharing mode, the 
read/write pointer information is kept on the remote computer. 
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43H — Change File Mode (CHMOD) 


Purpose 

Changes the file mede ef the specified file. 


Examples 

; To Get Attributes 


MOV 

AX,SEG FName 

;File Name 

MOV 

DS,AX 


MOV 

DX, OFFSET FName 

;DS:DX points to ASCIIZ path name 

MOV 

AL,0 

; Indi cate get 

MOV 

AH,43H 

; Function-Change File Mode 

INT 

21H 

; Issue request to DOS 

JC 

Error 

; Error code in AX 

MOV 

Attribute, CX 

;Save Attribute 

Set Attributes 


MOV 

AX,SEG FName 

;File Name 

MOV 

DS,AX 


MOV 

DX, OFFSET FName 

;DS:DX points to ASCIIZ path name 

MOV 

AL,1 

; Indi cate set 

MOV 

AH,43H 

; Function-Change File Mode 

MOV 

CX, Attribute 

;Set Attribute 

INT 

21H 

; Issue request to DOS 

JC 

Error 

; Error code in AX 


Fname DB 

Attribute DW 


64 Dup (0) 

7 


ASCIIZ Name 

example: "c:\dir\File. ext", 0 
File Attribute 

example: OOOIH to set Read-Only 


Comments 


On entry, AL contains a function code, and DS:DX contains the address ef an 
ASCIIZ string with the drive, path, and filename. 

If AL centains 01 H, the file's attribute is set te the attribute in CX. See “The 
Disk Directory” on page 11 for the attribute byte description. If AL is OOH the 
file's current attribute is returned in CX. 
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Error codes are returned in AX. Issue function caii 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. 

Note: Oniy the Archive (20H), Read-Oniy (01 H), System (04H) and Hidden 

(02H) bits can be changed. Aii other bits of CX must be 0, otherwise, 
an error may be indicated. 

Network Access Rights: To change the archive bit (AL=20H), no access 
rights are required. To change any other bit. Create access rights are 
required. 
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44H — I/O Control for Devices 


Purpose 

Sets or gets device information associated with open device handles, or 
sends control strings to the device handle or receives control strings from 
the device handle. 


See Appendix C, “I/O Control for Devices (lOCtI)” on page 273 for full details 
on this function call. 


AL 

= 

OOH 

AL 

= 

01 H 

AL 


02H 

AL 

= 

03H 

AL 

= 

04H 

AL 

= 

OSH 

AL 

= 

06H 

AL 

= 

07H 

AL 

= 

OSH 

AL 

= 

OOH 

AL 

= 

OAH 

AL 

= 

OBH 

AL 

= 

OCH 

AL 

= 

ODH 

AL 

= 

OEH 

AL 

= 

OFH 

AL 

= 

10H 

AL 

— 

11H 


Get device information (returned In DX). 

Set device Information (determined by DX). DH must be 0 for 
this call. 

Read from character device 
Write to character device 
Read from block device 
Write tc bicck device 
Get input status 
Get output status 

Determine if a particular block device is removable 

Determine if a logical device is local or remote 

Determine if a handle is Iccal or remote 

Change sharing retry count 

Issue handle generic lOCtI request 

Issue block device generic lOCtI request 

Get logical drive 

Set Icgical drive 

QuerylOCtIHandle 

QuerylOCtIDevice 
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45H — Duplicate a File Handle (DUP) 


Purpose 

Returns a new file handle for an epen file that refers to the same file at the 
same position. 

Examples 


MOV 

AH,45H 

Function Call - 
Duplicate a Handle 

MOV 

BX, Handle 

Select File 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

NewHandle, AX 

Save New Handle 

Handle 

DW ? 

File Handle (from Open / Create) 

NewHandle 

DW ? 

File Handle that duplicates Handle 


Comments 

On entry, BX contains the file handle. On return, AX contains the returned 
file handle. 

Error codes are returned in AX. Issue functien call 59H (Get Extended Errer) 
for additional information about the error class, suggested action, and 
location. 

Note: If you move the read/write pointer of either handle by a read, write, or 
LSEEK function call, the pointer for the other handle is also changed. 
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46H — Force a Duplicate of a Handle (FORCDUP) 


Purpose 

Forces the handle in CX to refer to the same file at the same position as the 
handle in BX. 


Examples 


MOV 

AH,46H 

Function Call - 
Force Duplicate a Handle 

MOV 

BX, Handle 

Select file 

MOV 

CX, NewHandle 

Select new definition of File 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 


Handle DW ? 

NewHandle DW ? 


; File Handle (from Open/Create) 

; File Handle that duplicates Handle 


Comments 

On entry, BX contains the file handle. CX contains a second file handle. On 
return, the CX file handle refers to the same file at the same position as the 
BX file handle. If the CX file handle was an open file, it is closed first. If you 
move the read/write pointer of either handle, the pointer for the other handle 
is also changed. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. 
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47H — Get Current Directory 


Purpose 

Places the full path name (starting from the root directory) of the current 
directory for the specified drive In the area pointed to by DS:SI. 


Examples 

MOV 

AX,SEG DName 

Directory Name Buffer 


MOV 

DS,AX 



MOV 

SI, OFFSET DName 

0S:SI points to buffer 


MOV 

DLjDri ve 

Select Drive 


MOV 

AH,47H 

Function-Get Current Dir 


INT 

21H 

Issue request to DOS 


JC 

Error 

Error code in AX 


Dri ve 

DB ? 

Drive (0=current, 1=A:, 2=b:, 


DName 

DB 64 DUP(?) 

ASCIIZ Directory Name Returned 




example: "dirl\dir2",0 


Comments 

The drive letter Is not part of the returned string. The string does not begin 
with a backslash and Is terminated by a byte containing OOH. 

Error codes are returned In AX. Issue function call 59H (Get Extended Error) 
for additional Information about the error class, suggested action, and 
location. 
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48H — Allocate Memory 

Allocates the requested number of paragraphs of memory. 

Examples 

MOV 

MOV 
INT 
JNC 
MOV 


INT 

Done: 

MOV 

MOV 


Paragraphs DW ? ; Size requested in paragraphs 

; (Bytes allocated is 16 * Paragraphs) 
BlockSeg DW ? ; BlockSeg address of allocated memory 


Comments 

On entry, BX contains the number of paragraphs requested. On return, AX:0 
points to the allocated memory block. If the allocation fails, BX returns the 
size of the largest block of memory available in paragraphs. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. 


AH,48H ; Function Call - 

; A1 1 ocate Memory 

BX, Paragraphs ; Paragraphs Desired 

21H ; Issue request to DOS 

Done 

AH,48H ; Function Call - 

; A1 1 ocate memory 

; BX set to largest available memory 
21H ; Issue request to DOS 

BlockSeg, AX ; Save BlockSeg of memory 

Paragraphs, BX 


Appendix B. PC DOS 7 Function Calls 227 



49H — Free Allocated Memory 


Purpose 

Frees the specified aiiocated memory. 


Examples 

MOV 

AH,49H 

; Function Call - Free Memory 

MOV 

ES, BlockSeg 

; Set address to free 

INT 

21H 

; Issue request to DOS 

JC 

Error 


BlockSeg 

DW ? 

; BlockSeg address of allocated memory 


Comments 

On entry, ES contains the segment of the biock to be returned to the system 
pooi. On return, the biock of memory is returned to the system pooi. 

Error codes are returned in AX. Issue function caii 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. 
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4AH — Modify Allocated Memory Blocks (SETBLOCK) 

Purpose 

Modifies allocated memory blocks to contain the new specified block size. 


Examples 

MOV 

AH,4AH 

Function Call - 

MOV 

ES, BlockSeg 

Modify Allocated Memory; allocate memory 
Set address to free 

MOV 

BX, BlockSize 

New size (may be larger or smaller) 

INT 

21H 

Issue request to DOS 

JNC 

Done 


MOV 

AH,4AH 

Function Call - 

INT 

21H 

A1 1 ocate memory 

BX set to largest available Size 

Issue request to DOS 

Done: 

MOV 

Size,BX 


BlockSeg 

DW ? 

Segment address of allocated memory 

BlockSize 

DW ? 

Size requested in paragraphs 



(Bytes allocated is 16 * Size) 

Comments 

Error codes are 

returned In AX. Issue function call 59H (Get Extended Error) 


for additional Information about the error class, suggested action, and 
location. 

Note: This call Is often used to set the size of a program before using 

function call 31 H (Terminate Process and Remain Resident). Use the 
program segment prefix. This value can be obtained using function 
call 62H (Get Program Segment Prefix Address). Another use Is to 
release memory to prepare for using function call 4BH (Load or 
Execute a Program). 
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4BH — Load or Execute a Program (EXEC) 


Purpose 

Allows a program to load another program Into memory and may choose to 
begin execution of It. 

Examples 


; To Execute a Program 


MOV 

AH,4BH 

Function Call - Execute a Program 

MOV 

AL,0 

Indicate execute program 

MOV 

CXjSEG Parms 

Program parameters 

MOV 

ES,CX 


MOV 

BX, OFFSET Parms 

ES:BX points to parameter block 

MOV 

CX,SEG PName 

Program name 

MOV 

DS,CX 


MOV 

DX, OFFSET PName 

DS:DX points to program name 

MOV 

WORD PTR StackSave+0,SP 

Save stack poi nter 

MOV 

WORD PTR StackSave+ZjSS 


INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 


; Note: All Registers (except CS:IP) Destroyed 


; Program Runs here 


CLI 


Protect from stack usage 

MOV 

SS,WORD PTR StackSave+2 

Restore stack pointer 

MOV 

SP,WORD PTR StackSave+0 


STI 


Enable interrupts 

MOV 

AH,4DH 

Function Call - Get Return Code 

INT 

2IH 

Issue request to DOS 

MOV 

RetCode,AX 

Save return code 

To 

Load an Overlay 


MOV 

AH,4BH 

Function Call - Execute a Program 

MOV 

AL,3 

Indicate load overlay 

MOV 

CXjSEG OParms 

Overlay parameters 

MOV 

ES,CX 


MOV 

BX, OFFSET OParms 

ES:BX points to parameter block 

MOV 

CX,SEG PName 

Overlay name 

MOV 

DS,CX 


MOV 

DX, OFFSET PName 

DS:DX points to overlay filename 

INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 
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PName 

DB 

64 Dup (0) 

ASCIIZ Name 





example: "c:\dir\File. ext", 0 


Parms 

LABEL 

WORD 

Program parameters 


Env@ 

DW 

7 

Environment segment address 





Value of OOOOH indicates copy 

EXEC' ers 




Envi ronment 


Cmd0 

DD 

7 

Command line address 


FCBie 

DD 

7 

FCB Image to set to New PSP+5CH 


FCB2@ 

DD 

7 

FCB Image to set to New PSP+6CH 


StackSave 

DD 

7 

Stack pointer save area 


RetCode 

DW 

7 

Program return code 





(see function code 4DH for more 

information 

OParms 

LABEL 

WORD 

Overlay parameters 


Load0 

DW 

7 

Overlay load segment address 


RelocFactor 

DW 

7 

Relocation factor to apply (for 

.EXE files) 


Comments 

Error codes are returned in AX. Issue function caii 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function caii 59H. 

The foiiowing function vaiues are ailowed in AL: 


Function 

Value 

Description 

OOH 

Load and execute the program. A program segment prefix is 
established for the program; terminate and Ctrl-Break addresses are set 
to the instruction after the EXEC system call. 


Note: When control Is returned, all registers are changed, including the 
stack. You must restore SS, SP, and any other required registers 
before proceeding. 

OSH 

Load, do not create the program segment prefix, and do not begin 
execution. This is useful in loading program overlays. 


Oniy the first 20 fiie handies are duplicated in the newiy created process 
after an EXEC, uniess the file was opened with the inheritance bit set to 1. 
This means that the parent process has controi over the meanings of 
standard input, output, auxiiiary, and printer devices. The parent couid, for 
exampie, write a series of records to a fiie, open the fiie as standard input, 
open a iisting fiie as standard output, and then execute a sort program that 
takes its input from standard input and writes to standard output. 
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Also inherited (or copied from the parent) is an “environment.” This is a 
block of text strings (less than 32KB total) that conveys various configuration 
parameters. The following is the format of the environment (always on a 
paragraph boundary): 



Typically the environment strings have the form: 
parameter = value 

Following the byte of 0 in the environment is a WORD that indicates the 
number of other strings following. Following this is a copy of the DS:DX 
filename passed to the child process. For example, the string VERIFY=ON 
could be passed. A 0 value of the environment address causes the newly 
created process to inherit the original environment unchanged. The segment 
address of the environment is placed at offset 2CFI of the program segment 
prefix for the program being invoked. 

Errors codes are returned in AX. Refer to “Responding to Errors” on 
page 138 and “Extended Error Codes” on page 138 for more information on 
the codes returned. 

Note: When your program received control, all available memory was 

allocated to it. You must free some memory (see call 4AH) before 
EXEC can load the program you are invoking. Normally, you would 
shrink down to the minimum amount of memory you need, and free 
the rest. 
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4CH — Terminate a Process (EXIT) 


Purpose 


Examples 


Terminates the current process and transfers control to the invoking process. 


MOV 

AH,4CH 

; Function Call - Terminate a Process 

MOV 

AL, ErrorCode 

; Set ERRORLEVEL 

INT 

21H 

; Issue request to DOS 

INT 

20H 

; Be safe if running on PC/DOS 1.1 

ErrorCode 

DB ? 

; Error Code (sets ERRORLEVEL if EXEC 
; by COMMAND.COM) 


Comments 


In addition, a return code can be sent. The return code can be interrogated 
by the batch subcommands IF and ERRORLEVEL and by the wait function call 
4DH. All files epened by this process are closed. 
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4DH — Get Return Code of a Subprocess (WAIT) 


Purpose 

Gets the return code specified by another process either through function 
caii 4CH or function cali 31 H. It returns the Exit code oniy once. 


Examples 


MOV 

AH,4DH 

; Function Call - Get Return Code 

INT 

21H 

; Issue request to DOS 

MOV 

RetCode, AX 

; Save return code 


RetCode LABEL WORD 

Ext tCode DB ? 

Ext tType DB ? 


Program return code 
ERRORLEVEL value 
Method used to exit (AH): 

OOH - for normal termination 
OlH - for termination by Ctrl -Break 
02H - for termination as a result 
of a critical device error 
OSH - for termination by call 31H 


Comments 

The iow byte of the exit code contains the information sent by the exiting 
routine. 
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4EH 


Find First Matching Fiie (FIND FIRST) 


Purpose 

Finds the first fiiename that matches the specified fiie specification. 

Examples 


MOV 

AH,1AH 

Function Call - Set DTA Address 

MOV 

CX,SEG DTA 

Address buffer for found file 

MOV 

DS,CX 


MOV 

DX, OFFSET DTA 


INT 

21H 

Issue request to DOS 

MOV 

AH,4EH 

Function Call - ASCIIZ Find First 

MOV 

CX,SEG FName 

Directory or filename 

MOV 

DS,CX 


MOV 

DX, OFFSET FName 

DS:DX points to ASCII filename 

MOV 

CX, Attribute 

Set Match Attribute 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 


DTA LABEL BYTE ; Find return information 

DB 21 DUP(O) ; Reserved for PC DOS 7 to continue find 

FileAttr DB ? ; Matched files attribute low byte 

FileTime DW ? ; File time 

FileDate DW ? ; File date 

FileSize DD ? ; File size 

FileNameExt DB "????????. ???",0 ; Filename and extension 

FName DB 64 DUP (0) ; ASCIIZ Name 

; example: "c:\dir\*.*",0 

Attribute DW ? ; Select files attribute 


Combination of following: 
0001H=Read only 
0002H=Hidden 
0004H=System 
0008H=Volume label 
0010H=Di rectory 
0040H=Reserved 
0080H=Reserved 


Appendix B. PC DOS 7 Function Calls 235 


Notes: 

1. If the attribute is 0, only normal file entries are found. Entries for volume 
label, subdirectories, hidden files, and system files are not returned. 

2. If the attribute field is set for hidden files, or system files, or directory 
entries, it is to be considered as an inclusive search. All normal file 
entries plus all entries matching the specified attributes are returned. To 
look at all directory entries except the volume label, the attribute byte 
may be set to hidden + system + directory (all 3 bits on). 

Comments 

The filename in DS:DX can contain global filename characters. The ASCIIZ 
string cannot contain a network path. See function call 11H (Search for First 
Entry) for a description of how the attribute bits are used for searches. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function call 59H. 

Note: The name and extension of file found is returned as an ASCIIZ string. 
All blanks are removed from the name and extension, and, if an 
extension is present, it is preceded by a period. 
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4FH — Find Next Matching Fiie (FIND NEXT) 


Purpose 

Finds the next directory entry matching the name that was specified on the 
previous Find First or Find Next function cail. 



Error codes are returned in AX. Issue function cali 59H (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. 
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50H — Set Program Segment Prefix Address 


Purpose 

Sets the segment address of the current programs, program segment prefix. 


Examples 


MOV 

BX, SEGMENT PSP 

; Segment Address of New PSP 

MOV 

AH,50H ; 

Function Call - Set PSP Address 

INT 

21H ; 

Issue request to DOS 


9 

No Return 

SEGMENT_PSP 

DW ? 

; Segment Address of PSP 
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51 H — Get Program Segment Prefix Address 


Purpose 


Examples 


Comments 


Returns the segment address of the currently executing programs, program 
segment prefix. 


MOV AH,51H 

INT 21H 

JC Error 


Function Call - Get PSP Address 
Issue request to DOS 
Error Code in AX 


MOV SEGMENT_PSP,BX ; Save PSP Address 
SEGMENT_PSP DW ? ; Segment Address of PSP 


This function is identical to Interrupt 21 H functien 62H. 
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54H — Get Verify Setting 


Purpose 

Returns the value of the verify flag. 


Exampies 


MOV 

AH,54H 

; Function Call - Get VERIFY Setting 

INT 

21H 

; Issue request to DOS 

MOV 

VERIFY, AL 

; Save VERIFY State 

VERIFY 

DB ? 

; VERIFY State: 



; 0 = OFF 



; 1 = ON 


Comments 

On return, AL returns OOH if verify is OFF, 01 H if verify is ON. Note that the 
verify switch can be set through call 2EFI (Set/Reset Verify Switch). 
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56H — Rename a File 


Purpose 

Renames the specified file. 

Examples 


MOV 

AH,56H 

; Function Call - ASCIIZ Rename File 

MOV 

CX,SEG FName 

; File Name 

MOV 

DS,CX 


MOV 

DX, OFFSET FName 

; DS:DX points to original name 

MOV 

CXjSEG NewName 

; New File Name 

MOV 

ES,CX 


MOV 

DI, OFFSET NewName 

; ES:DI points to rename 

INT 

21H 

; Issue request to DOS 

JC 

Error 

; Error code in AX 

FName 

DB 64 DUP (0) 

; ASCIIZ Name 

; example: "c:\dir\abc.lst",0 

NewName 

DB 64 DUP (0) 

; ASCIIZ Name 

; example: "\dir\xyz.lst",0 


Comments 

If a drive Is used in the NewName string, it must be the same as the drive 
specified or implied in the Name string. The directory paths need not be the 
same, allowing a file to be moved to another directory and renamed in the 
process. Directory names can be changed but not moved. Global filename 
characters are not allowed in the filename. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function call 59H. 

Network Access Rights: Requires Create access rights. 
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57H — Get/Set File's Date and Time 


Purpose 

Examples 


Gets or sets a file's date and time. 


; To Get a File's Date and Time 


MOV 

AH,57H ; 

MOV 

AL,0 ; 

MOV 

BX, Handle ; 

INT 

2IH ; 

JC 

Error ; 

MOV 

Fi 1 eTime, CX ; 

MOV 

Fil eDate, DX ; 

; To Set a 

File's Date and Time 

MOV 

AH,57H ; 

MOV 

AL,1 ; 

MOV 

BX, Handle ; 

MOV 

CX, Fil eTime ; 

MOV 

DX, Fil eDate ; 

INT 

2IH ; 

JC 

Error ; 

Handle 

DW ? ; 

Fi 1 eTime 

DW ? ; 

Fi 1 eDate 

DW ? ; 


Function Call - Get/Set Date and Time 

Indicate get 

Select file 

Issue request to DOS 

Error code in AX 

Save Time 

Save Date 


Function Call - Get/Set Date and Time 
Indicate Set 
Select file+ 

Set Time 
Set Date 

Issue request to DOS 
Error code in AX 


File Handle (from Open / Create) 
File Time 
File Date 


Comments 

The date and time formats are the same as those for the directory entry 
described in Chapter 5 of this book. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function call 59H. 
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5800H — Get Allocation Strategy 


Purpose 

Returns the scheme in which PC DOS 7 uses te ailecate memory. 


Examples 


MOV 

AH,5800H 

; Function Call - Get Allocation Strategy 

INT 

21H 

; Issue request to DOS 

JC 

Error 


MOV 

STRATEGY, AX 

; Save Allocation Strategy 

STRATEGY 

DW ? 

; Allocation Strategy 


Comments 

The foiiowing tabie describes the aiiocation strategies returned vaiues: 


Table 1 (Page 1 of 2). Allocation Strategies 

Value 


Description 

FIRST_FIT_LOW 

OOOOH 

Search conventional memory for an 
available block having the lowest 
address. This is also the default 
strategy. 

BEST_FIT_LOW 

0001 H 

Search conventional memory for an 
available block that closely matches 
the requested size. 

LAST_FIT_LOW 

0002H 

Search conventional memory for an 
available block at the highest address. 

FIRST_FIT_HIGH 

0080H 

Search the upper-memory area for an 
available block at the lowest address. 

If no block is found then the search 
continues in the conventional memory. 

BEST_FIT_HIGH 

0081 H 

Search the upper-memory area for an 
available block that closely matches 
the requested size. If no block is found 
then the search continues in the 
conventional memory. 

LAST_FIT_HIGH 

0082H 

Search the upper-memory area for an 
available block at the highest address. 

If no block is found then the search 
continues in the conventional memory. 
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Table 1 (Page 2 of 2). Allocation Strategies 

Value 


Description 

FIRST_FIT_HIGHONLY 

0040H 

Search the upper-memory area for an 
available block at the lowest address. 

BEST_FIT_HIGHONLY 

0041 H 

Search the upper-memory area for an 
available block that closely matches 
the requested size. 

LAST_FIT_HIGHONLY 

0042H 

Search the upper-memory area for an 
available block at the highest address. 
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5801 H — Set Allocation Strategy 


Purpose 

Sets the scheme by which PC DOS 7 uses to allocate memory. 


Examples 

MOV 

BX, STRATEGY 


MOV 

AH,5801H 


INT 

21H 


JC 

Error 


STRATEGY 

DW ? 


Allocation Strategy 

Function Call - Set Allocation Strategy 
Issue request to DOS 


Allocation Strategy 


Comments 

The strategy used is the same as described in the table on Table 1 on 
page 243. 


After the function is called the carry flag will be clear if it has been 
successful!. If the carry flag is set the AX register contains an error, which 
could be 0001 H, indicating that the strategy is not one of the ones specified. 
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5802H — Get Upper-Memory Link 


Purpose 

Specifies whether programs can aiiocate memory from the upper-memory 
area. 

Examples 

MOV AH,5802H ; Function Call - Get Upper-Mem Link 

INT 21H ; Issue request to DOS 

MOV UM_LINK,AX ; Save Upper-Memory Link Information 

UM_LINK DB ? ; Upper-Memory Linked 

; 1 = Linked 
; 0 = Not Linked 

Comments 
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5803H — Set Upper-Memory Link 


Purpose 

Allows you to link or unlink the upper-memory area. If linked, a program 
may allocate memory from the upper-memory area. 


Examples 

MOV 

BX,UM LINK 


MOV 

AH,5802H 


INT 

2IH 


JC 

Error 


; Set Upper-Memory Link Information 
Function Call - Set Upper-Mem Link 
Issue request to DOS 
AX contains the error value 
OOOIH ERROR_INVALID_FUNCTION 
0007H ERROR_ARENA_TRASHED 


UM_LINK DB ? ; Upper-Memory Linked 

; 1 = Link Upper-Memory Area 
; 0 = Unlink Upper-Memory Area 


Comments 


The return of the 0001 H error (ERROR_INVALID_FUNCTION) could Indicate 
that PC DOS 7 has been loaded without DOS=UMB being specified in the 
CONFIG.SYS file. 
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59H — Get Extended Error 


Purpose 

Returns additional error information, such as the error class, location, and 
recommended action. 

Examples 


PUSH 

DX ; 

Save Registers 

PUSH 

SI 


PUSH 

DI 


PUSH 

ES 


PUSH 

DS 


MOV 

AH,59H ; 

Function Call - Get Extended Error 

MOV 

BX,0 ; 

Version 0 information 

INT 

21H ; 

Issue request to DOS 

POP 

DS ; 

Restore registers 

POP 

ES 


POP 

DI 


POP 

SI 


POP 

DX 


MOV 

ExtError, AX ; 

Save error code 

MOV 

ErrorCl ass, BH ; 

Save error class 

MOV 

ErrorAction,BL ; 

Save error action 

MOV 

ErrorLocation,CH; 

Save error location 

ExtError 

DW ? ; 

DOS extended error 

ErrorCl ass 

DB ? ; 

Class of error 

ErrorAction 

DB ? ; 

Suggested action 

ErrorLocation 

DB ? ; 

System area effected 


Comments 


This function call returns the error class, location, and recommended action, 
in addition to the return code. Use this function call from: 

• Interrupt 24H error handlers 

• Interrupt 21 H function calls that return an error in the carry bit 

• FCB function calls that return FFH. 
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On return, the registers contents of DX, SI, Dl, ES, CL, and DS are destroyed. 

Error Return in Carry Bit 

For function caiis that indicate an error by setting the carry fiag, the correct 
method for performing function caii 59H is: 

• Load registers. 

• Issue interrupt 21 H. 

• Continue operation, if carry not set. 

• Disregard the error code and issue function cail 59H to obtain additionai 
information. 

• Use the vaiue in BL to determine the suggested action to take. 

Error Status in AL 

For function oaiis that indicate an error by setting AL to FFH, the correct 
method for performing function caii 59H is: 

• Load registers. 

• Issue interrupt 21 Fi. 

• Continue operation, if error is not reported in AL. 

• Disregard the error code and issue function caii 59H to obtain additionai 
information. 

• Use the vaiue in BL to determine the suggested action to take. 
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5AH — Create Unique File 


Purpose 

Generates a unique filename, and creates that file in the specified directory. 


Examples 


MOV 

AH,5AH 

Function Call - Create a 



Unique File 

MOV 

CX,SEG Di rName 

Directory name 

MOV 

DS,CX 


MOV 

DX, OFFSET Di rName 


MOV 

CX, Attribute 

File attribute 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

Handle, AX 

Save file handle for following 
Operations 

Di rName 

DB "?? .. ??V',0 

HR "7777?777 777" 

ASCIIZ name 

example in : "c:\dirV',0 
example out: "c:\dir\file",0 

Handle 

DW ? 

File handle 

Attribute 

DW ? 

Select file's attribute 


Comments 

On entry, AH contains 5AH. If no error has occurred, the file is opened in 
compatibility mode with Read/Write access. The read/write pointer is set at 
the first byte of the file and AX contains the file handle and the filename is 
appended to the path specified in DS:DX. 

This function call generates a unique name and attempts to create a new file 
in the specified directory. If the file already exists in the directory, then 
another unique name is generated and the process is repeated. Programs 
that need temporary files should use this function call to generate unique 
filenames. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
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Codes” on page 138 for more information on the codes returned from 
function caii 59H. 

Note: The fiie created using this function cali is not automaticaiiy deieted at 
program termination. 

Network Access Rights: Requires Create access rights. 
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5BH — Create New File 


Purpose 

Creates a new file. 

Examples 


MOV 

AH,5BH ; 

Function Call - Create a New File 

MOV 

CX,SEG FName ; 

File Name 

MOV 

DS,CX 


MOV 

DX, OFFSET FName 


MOV 

CX, Attribute 


INT 

21H ; 

Issue request to DOS 

JC 

Error ; 

Error code in AX 

MOV 

Handle, AX ; 

Save File Handle for following operations 

FName 

DB 64 DUP (0) 

; ASCIIZ Name 



; example: "c:\dir\file",0 

Handle 

DW ? 

; File Handle 

Attribute 

DW ? 

; Select File's Attribute 


Comments 

This function call is the same as function call 3CH (Create), except it will fail 
if the filename already exists. The file is created in compatibility mode for 
reading and writing and the read/write pointer is set at the first byte of the 
file. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the nodes returned from 
funotion call 59H. 

Network Access Rights: Requires Create access rights. 
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5CH — Lock/Unlock File Access 


Purpose 

Locks or unlocks a single range of bytes In an opened file. This function call 
provides database services that are useful in maintaining database integrity 
in a network environment. 

Examples 


; To Lock a Single Range 


MOV 

AH,5CH 

Function Call - 
Access Lock/Unlock File 

MOV 

AL,0 

Indicate lock 

MOV 

BX, Handle 

Select file 

MOV 

DX,W0RD PTR Position+0 

Set position 

MOV 

CX,W0RD PTR Position+2 


MOV 

DI,W0RD PTR Llength+0 

Set length 

MOV 

SI, WORD PTR Llength+2 


INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 

; To Unlock 

a Single Range 


MOV 

AH,5CH 

Function Call - 
Lock/Unlock File Access 

MOV 

AL,I 

Indicate unlock 

MOV 

BX, Handle 

Select file 

MOV 

DX,W0RD PTR Position+0 

Set position 

MOV 

CX,W0RD PTR Position+2 


MOV 

DI,W0RD PTR Llength+0 

Set length 

MOV 

SI, WORD PTR Llength+2 


INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 

Handle 

DW ? 

File Handle 

Posi ti on 

DO ? 

Start of Range 

Llength 

DO ? 

Length of Range 
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Comments 


The Lock/Unlock function calls should only be used when a file is opened 
using the DenyRead or DenyNone sharing modes. These modes do no local 
buffering of data when accessing files on a network disk. 

AL = OOH Lock 

Lock provides a simple mechanism for excluding other processes' read/write 
access to regions of the file. If another process attempts to read or write in 
such a region, its system call is retried the number of times specified with 
the system retry count set by lOCTL. If, after those retries, no success 
occurs, a general failure error is generated, signaling the condition. The 
number of retries, as well as the length of time between retries, can be 
changed using function call 440BH (lOCTL Change Sharing Retry Count). 

The recommended action is to issue function call 59H (Get Extended Error) to 
get the error code, in addition to the error class, location, and recommended 
action. The locked regions can be anywhere in the logical file. Locking 
beyond end-of-file is not an error. It is expected that the time in which 
regions are locked will be short. Duplicating the handle duplicates access to 
the locked regions. Access to the locked regions is not duplicated across the 
EXEC system call. Exiting with a file open and having issued locks on that 
file has undefined results. 

Programs that may be cancelled using INT 23H or INT 24H should trap these 
interrupts and release the locks before exiting from the program. The proper 
method for using locks is not to rely on being denied read or write access, 
but to attempt to lock the region desired and examining the error code. 

AL = 01H Unlock 

Unlock releases the lock issued in the lock system call. The region specified 
must be exactly the same as the region specified in the previous lock. 

Closing a file with locks still in force has undefined results. Exiting with a file 
open and having issued locks on that file has undefined results. 

Programs that may be abended using INT 23H or INT 24H should trap these 
interrupts and release the lock before exiting from the program. The proper 
method for using locks is not to rely on being denied read or write access 
but rather attempting to lock the region desired and examining the error 
code. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function call 59H. 
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5D0AH — Set Extended Error 


Purpose 

This function sets the error class, location suggested action and other 
information that will be returned by the next call to function 59H Get 
Extended Error. 

Examples 

MOV DX, SEG ERR0R_INF0 

MOV DS,DX 

MOV DX, OFFSET ERR0R_INF0 

MOV AHjSDOAH ; Function Call - Set Extended Error 

INT 21H ; Issue request to DOS 

ERR0R_INF0 STRUC 


ExtendedErr 

DW 

7 

Extended Error Code 

ErrorCl ass 

DB 

7 

Error Class 

ErrorAction 

DB 

7 

Suggested Action 

ErrorLoc 

DB 

7 

Location of Error 

errCL 

DB 

7 

CL Register 

errOX 

DW 

7 

DX Register 

errSI 

DW 

7 

SI Register 

errOI 

DW 

7 

DI Register 

errOS 

DW 

7 

DS Register 

errES 

DW 

7 

ES Register 

errReserved 

DW 

7 

Reserved Word 

errUID 

DW 

7 

USER ID 

errPID 

DW 

7 

Program ID 


Comments 

Please refer to “Responding to Errors” on page 138 for details of the 
possible values that may be used In the ERROR_INFO structure. 
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5E00H — Get Machine Name 


Purpose 

Returns the character identifier ef the iocai cemputer. 

Examples 


MOV 

AX,SEG CNAME 

Name buffer 


MOV 

DS,AX 



MOV 

DX OFFSET CNAME 



MOV 

AX,5E00H 

Function Cal 1 - 




Get Machine Name 


INT 

21H 

Issue request to 

DOS 

JC 

Error 

Error code in AX 


MOV 

NameFl ag,CH 

Save name number 

i ndi cator 

MOV 

NameIDjCL 

Save NETBIOS name 

number 


CName 

DB 

"777777777777777" 0 

; ASCIIZ computer name 

NameFl ag 

DB 

7 

; 0 = Name is not set 




; 1 = Name is set 

NamelD 

DB 

7 

; NETBIOS name number 


Comments 

Get Machine Name returns the text of the current computer name to the 
caiier. The computer name is a 15-character byte string padded with spaces 
and foiiowed by a OOH byte. If the computer name was never set, register 
CH is returned with OOH and the vaiue in the CL register is invaiid. The iBM 
PC Locai Area Network Services program must be ioaded for the function 
caii to execute properiy. 
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5E02H — Set Printer Setup 


Purpose 

Specifies an initiai string for printer fiies. 


Examples 


MOV 

AX,5E02H ; 

Function Cal 1 - 



Set Printer Setup 

MOV 

BX, Index ; 

Redirection List Index 

MOV 

CXjSize ; 

String size 

MOV 

SI ,SEG Stri ng ; 

String Buffer 

MOV 

DS,SI 


MOV 

SI, OFFSET String 


INT 

21H ; 

Issue request to DOS 

JC 

Error ; 

Error code in AX 

Index 

DW ? ; 

Redirection List Index 

Size 

DW N ; 

String size (Maximum 64) 

Stri ng 

DB N DUP(?) ; 

Printer Setup String 


Comments 

The string specified is put in front of ali fiies destined fer a particuiar netwerk 
printer. Set Printer Setup aiiews muitipie users of a singie printer to specify 
their own mode of operation for the printer. BX is set te the same index that 
is used in function cali 5F02H (Get Redirectien List Entry). An error code is 
returned if print redirection is paused or if the IBM PC Lecai Area Network 
Services program is not ioaded. 

Error codes are returned in AX. Issue functien call 59H (Get Extended Errer) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more infermatien on the codes returned from 
function call 59H. IMPORTANT: The redirection index value may change if 
function call 5F03H (Redirect Device) or function call 5F04H (Cancel 
Redirectien) is issued between the time the redirection list is scanned and 
the functien call 5E02FI (Set Printer Setup) is issued. Therefore, we 
recommend that you issue Set Printer Setup immediately after you issue 
“Get Redirection List .” 
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5E03H — Get Printer Setup 


Purpose 

Returns the printer setup string for printer files. 


Examples 


MOV 

AX,5E03H ; 

Function Cal 1 - 



Get Printer Setup 

MOV 

BX, Index ; 

Redirection List Index 

MOV 

CXjSEG String ; 

String Buffer 

MOV 

ES,CX 


MOV 

DI, OFFSET String 


INT 

21H ; 

Issue request to DOS 

JC 

Error ; 

Error code in AX 

MOV 

Ssize, CX ; 

Save String size 

Index 

DW ? ; 

Redirection List Index 

Ssize 

DW ? ; 

String size 

Stri ng 

DB 64 DUP(?) ; 

Printer Setup String 


Comments 

This function call returns the printer setup string which was specified using 
the function call 5E02H (Set Printer Setup). The setup string is attached to all 
files destined for a particular printer. The value In BX Is set to the same 
Index Issued in function call 5F02H (Get Redirection List). Error code 1 
(Invalid function number) is returned if the IBM PC Local Area Network 
Services is not loaded. 

Error codes are returned In AX. Issue function call 59H (Get Extended Error) 
for additional Information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function call 59H. 

IMPORTANT: The redirection Index value may change If function call 5F03H 
(Redirect Device) or function call 5F04H (Cancel Redirection) Is Issued 
between the time the redirection list Is scanned and the function call 5E03H 
(Get Printer Setup) Is Issued. Therefore, we recommend that you Issue “Get 
Printer Setup” immediately after you Issue “Get Redirection List.” 
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5F02H — Get Redirection List Entry 


Purpose 

Returns nonlocal network assignments. 


Exampies 


MOV 

BX,0 

Get_Loop: 

MOV 

Index, BX 

MOV 

AX,5F02H 

MOV 

SI,SEG device 

MOV 

DS,SI 

MOV 

SI, OFFSET device 

MOV 

DI,SEG info 

MOV 

ES,DI 

MOV 

DI, OFFSET inf 

PUSH 

BX 

PUSH 

DX 

PUSH 

BP 

INT 

21H 

POP 

BP 

POP 

DX 

JC 

CheckEnd 

MOV 

Status, BH 

MOV 

Type,BL 

MOV 

UserParm,CX 

POP 

BX 

INC 

BX 

JMP 

Get_Loop 

CheckEnd: 

POP 

BX 

CMP 

AX, 18 

ONE 

Error 

Index 

DW ? 

Devi ce 

DB 128 DUP(?) 

Status 

DB ? 


start at beginning of list 
Get next entry 
Redirection list index 
Function Cal 1 - 
Get redirection list entry 
"PRN" is possible 

DS:SI points to local name 


ES:DI points to buffer address of network name 

Save registers 

Issue request to DOS 
Restore registers 

Error code in AX 
Save status 
Save type 

Save user parameter 
Set to next entry 


Balance state 
End of 1 i St? 
No! 


Redirection list index (0 based) 
ASCIIZ device name 
example: "LPTT'.O 
"A:",0 

Device status 

Bit 0=0 : Device is OK 
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UserParm 

DW 

7 

Type 

DB 

7 

Info 

DB 

128 DUP(? 


Bit 0=1 : Device in Error 
Bit 7-1 reserved 
User parameter 
Device type 

3 = NET USE device 

4 = NET USE drive 
NET USE network path 

example: "\\MYNODE\CDRIVE",0 


Comments 

The Get Redirection List Entry function caii returns the iist of network 
redirections that were created through function caii SFOSH (Redirect Device). 
Each caii returns one redirection, so BX shouid be increased by one each 
time to step through the iist. The contents of the iist may change between 
caiis. The end-of-iist is detected by error code 18 (no more fiies). Error code 
1 (invaiid function number) is returned if the iBM PC Locai Area Network 
Services program and iFSFUNC are not ioaded. 

if either disk or print redirection is paused, the function is not effected. 

Error codes are returned in AX. issue function caii 59i-i (Get Extended Error) 
for additionai information about the error ciass, suggested action, and 
iocation. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function caii 59i-i. 
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5F03H — Redirect Device 


Purpose 

Causes a Redirector/Server connection to be made. 


Exampies 


MOV 

AX,5F03H 

Function Cal 1 - 
Redirect Device 

MOV 

SI,SEG Device 

Device Buffer 

MOV 

DS,SI 


MOV 

SI, OFFSET Device 


MOV 

DIjSEG Net Path info 

Information Buffer 

MOV 

ES,DI 


MOV 

DI, OFFSET Net Path 


MOV 

BL,Type 

Set Type 

MOV 

CX, UserParm 

Set User Parameter 

INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 

Devi ce 

DB "....",0 

ASCIIZ Device Name 
example: "LPTT'.O 
"A:",0 

UserParm 

DW ? 

User Parameter 

Type 

DB ? 

Device Type 

3 = NET USE Device 

4 = NET USE Drive 

Net Path 

DB 128 DUP(O) 



Comments 

This call defines the current directories for the network and defines 
redirection of network printers. 

• If BL = 03, the scurce specifies a printer, the destination specifies a 
network path, and the CX register has a wcrd that PC DOS 7 maintains 
for the programmer. Per compatibility with the IBM PC Local Area 
Network Services program, CX should be set to 0. Values other than 0 
are reserved for the IBM PC Lccal Area Netwcrk Services program. This 
word may be retrieved thrcugh functicn call 5F02H (Get Redirection List). 
All output destined fcr the specified printer is buffered and sent te the 
remote printer spoci for that device. The printers are redirected at the 
INT 17H level. 
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The source string must be PRN , LPT1, LPT2, or LPT3 each ended with a 
OOH. The destination string must point to a network name string of the 
following form: 

[computernameishortnamevprintdevice}] 

The destination string must be ended with a OOH. 

The ASCIIZ password (0 to 8 characters) for access to the remote device 
should Immediately follow the network string. The password must end 
with a OOH. A null (0 length) password is considered to be no password. 

• If BL = 4, the source specifies a drive letter and colon ending with OOH, 
the destination specifies a network path ending with OOH, and the CX 
register has a word that DOS maintains for the programmer. For 
compatibility with the IBM PC Local Area Network Services program, CX 
should be set to OOH. Values other than OOH are reserved for the IBM PC 
Local Area Network Services program. The value may be retrieved 
through function call 5F02H (Get Redirectien List). If the source was a 
drive letter, the association is made between the drive letter and the 
network path. All subsequent references to the drive letter are translated 
to references te the network path. If the source is an empty string, the 
system attempts to grant access to the destination with the specified 
password without redirecting any device. 

The ASCIIZ password for access to the remete path should immediately 
follow the network string. A null (0 length) password ended with OOH is 
considered to be no password. 

Error codes are returned in AX. Issue function call 59H for additional 
information about the error class, suggested action, and location. Refer 
to “Responding to Errors” on page 138 and “Extended Error Codes” on 
page 138 for more information on the codes returned frem function call 
59H (Get Extended Error) . 

Notes: 

1. Devices redirected through this function call are not displayed by the NET 
USE command. 

2. An error is returned if yeu try to redirect a drive while disk redirection is 
paused, or if you try to redirect a printer while print redirectien is 
paused. 
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5F04H — Cancel Redirection 


Purpose 

Cancels a previous redirection. 

Examples 


MOV 

AX,5F04H ; 

Function Cal 1 - 
Cancel redirection 

MOV 

SI,SEG Device ; 

Device buffer 

MOV 

DS,SI 


MOV 

SI, OFFSET Device 


INT 

21H ; 

Issue request to DOS 

JC 

Error ; 

Error code in AX 


Device DB " " ,0 ; ASCIIZ Device Name 

; example: "LPTT'.O 
; "A:",0 

; "\\Computer\Path",0 

Comments 

The redirection created by the Redirect Device function call (5F03H) is 
removed through the Cancel Redirection call. If the buffer points to a drive 
letter and the drive is associated with a network name, the association is 
ended and the drive is restored to its physical meaning. If the buffer points 
to PRN, LPT1, LPT2, or LPT3, and the device has an association with a 
network device, the association is terminated and the device is restored to 
its physical meaning. If the buffer points to a network path ending with OOH 
and a password ending with OOH, the association between the local machine 
and the network directory is terminated. 

An error is returned if you try to cancel a redirected file device while disk 
redirection is paused, or if you try to cancel a redirected printer while print 
redirection is paused. Error code 1 (invalid function number) is returned if 
the IBM PC Local Area Network Services program is not loaded. 

Error codes are returned in AX. Issue function call 59H (Get Extended Error) 
for additional information about the error class, suggested action, and 
location. Refer to “Responding to Errors” on page 138 and “Extended Error 
Codes” on page 138 for more information on the codes returned from 
function call 59H. 
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62H — Get Program Segment Prefix Address 


Purpose 

Returns the program prefix address. 


Examples 


MOV 

AH,62H 

; Function Call - 

; Get Program Segment Prefix Address 

INT 

21H 

; Issue request to DOS 

JC 

Error 

; Error code in AX 

MOV 

PSPSeg, BX 

; Save PSP address 

PSPSeg 

DW ? 

; Segment address of my PSP 


Comments 

The internal PSP address ter the currently executing process is returned in 
BX. 
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65H — Get Extended Country Information 


Purpose 

Returns extended country infermation. 


Examples 

; To get information 


MOV 

AH,65H 

Function Call - 





Get extended country information 


MOV 

AL,InfoID 

Data/f unction requested 
(I, 2, 4, 6 or 7). 



MOV 

BXjCodePage 

Set desired code page 
(-l=current, Set by function 

cal 1 

6602H) 

MOV 

CX,SizeBuffer 

Maximum data to return 
(must be >= 5) 



MOV 

DXjCountrylD 

Set desired Country ID 
(-l=current, set by function 

cal 1 

38H). 

MOV 

DI,SEG Buffer 

Information return buffer 



MOV 

ES,DI 




MOV 

DI, OFFSET Buffer 




INT 

21H 

Issue request to DOS 



JC 

Error 

Error code in AX 




Buffer LABEL BYTE 

; Format depends on AL value 
; AL=1 : Extended Country Information 


InfoID 

DB 

7 

; Type of info to get 

Cli nfoSize 

DW 

7 

; amount of data that follows 




; (limited by CX input) 

CountrylD 

DW 

7 

; Selected CountrylD 

CodePage 

DW 

7 

; Selected Code Page 


; See function call 38H, Country Information, for the format of the 
remainder of this buffer 


; AL=2 : Upper Case Table 

DB 2 ; Indicates Upper Case Table 

Uppercase® DD ? ; Address of Upper Case Table 

; AL=4 : File Upper Case Table 
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DB 4 

UpperCase0 DD ? 

; AL=6 : Collating Table 
DB 6 

Collate0 DD ? 

; AL=7 : DBCS Vector Table 
DB 7 

DBCSe DD ? 


Comments 

On entry, DX contains the ID of the country for which the extended 
information is needed. AL contains the ID value for the country. 

• If the country code and code page do not match, or if either one or both 
are invalid, an error code of 2 (file not found) is returned in AX. 

• The size requested in CX must be 5 or greater. If it is less than 5, an 
error code of 1 is returned in AX. 

• If the amount of information returned is greater than the size requested 
in CX, it is ended and no error is returned in AX. 

Note: For further information on the country information, see function call 
38H (Get or Set Country Dependent Information). 

The NLSFUNC DOS extension must be installed to get information for 
countries other than the Current Country. 

The uppercase table and the filename uppercase tables are 130 bytes long, 
consisting of a length field (2 bytes), followed by 128 uppercase values for the 
upper 128 ASCII characters. They have the following layout: 

Tsize DW 128 ; Table Size 

Table DB 128 DUP(?) ; Upper case versions of 80H to FFH 

The following formula can be used to determine the address of an uppercase 
equivalent for a lowercase character (ASClIJn) in the uppercase table or the 
filename uppercase table. 


; Indicates File Upper Case Table 
; Address of File Upper Case Table 


; Indicates Collate Table 
; Address of Collate Table 


; Indicates DBCS Vector Table 
; Address of DBCS Vector Table 


Examples 

ASCII_in -(256-table_len)+table_start= address of ASCII_out 

Where 
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ASCII_in = character to be generated 

tablejen = length of list of uppercase 
values (2 bytes) 

table_start = starting address of uppercase 
table (4 bytes) 

ASCII_out = uppercase value for ASCII_in 

If the value of ASClIJn is equal te or greater than (256-table_len), there is an 
uppercase equivalent for ASClIJn in the table. If it is lower than 
(256-tableJen), no uppercase equivalent exists in the table. 

The collate table is 258 bytes long, consisting of a length field (2 bytes) 
followed by 256 ASCII values, in the appropriate order. It has the following 
layout: 

Tsize DW 256 ; Table Size 

Table DB 256 DUP(?) ; Sort Weights for OOH to FFH 

The DECS vector is variable in length, consisting of a length field (two bytes) 
followed by one or more pairs of bytes in ascending order. It has the 
following layout: 


Tsize 

DW 

Nx2 

;List size 

1 

DB 

Start, end 

;DBCS vector 1 

2 

DB 

Start, end 

;DBCS vector 2 

N 

DB 

Start, end 

;DBCS vector n 


DB 

0,0 

;End marker 
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66H — Get/Set Global Code Page 


Purpose 

This function gets or sets the code page for the current country. 


MOV AX,6601H 

INT 21H 

JC Error 

MOV GlobalCP,BX 

MOV SystemCP,DX 


Function Cal 1 - 
Get Global Code Page 
Issue request to DOS 
Error code in AX 
Save Global Code Page 
Save DOS System Code Page 


MOV AX,6602H 

MOV BX,GlobalCP 

INT 21H 

JC Error 


Function Cal 1 - 
Set Global Code Page 
New Global Code Page 
Issue request to DOS 
Error code in AX 


Global CP DW 

SystemCP DW 


Current Code Page of DOS Country Information 
Code Page of DOS messages 
Often the default Code Page for the 
current country 


Comments 

PC DOS 7 moves the new code page data from the COUNTRY. SYS file to a 
resident country buffer area. PC DOS 7 uses the new code page to perform 
a Select to all attaohed devices that are set up for code page switching, (that 
is, have a code page switching device driver specified in CONFIG.SYS). If 
any device fails to be selected, an error code of 65 is returned in AX. The 
code page must be recognizable by the current country, and PC DOS 7 must 
be able to open and read from the country information fiie. Otherwise, the 
carry flag will be set on return and AX will contain 02 (fiie not found). 

Note: NLSFUNC must be instaiied to use this function caii, and ali the 
devices must be prepared in order for the Seiect function to be 
sucoessfui. 
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67H — Set Handle Count 


Purpose 

Permits more than 20 open files per process. 


Examples 


EntryPoi nt: 


MOV 

AH,62H 

Function Call - 
Get PSP Address 


INT 

21H 

Issue request to 

DOS 

JC 

Error 

Error code in AX 


MOV 

ES,BX 

Set Segment 


MOV 

AH,4AH 

Function Call - 
Set Memory Block 

Size 

MOV 

BX, paragraphs 

Set Size 


INT 

2IH 

Issue request to 

DOS 

JC 

Error 

Error code in AX 


MOV 

AH,67H 

Function Call - Set Handle Count 

MOV 

BX, NewHandles 

Set new handle count 

INT 

2IH 

Issue request to 

DOS 

JC 

Error 

Error code in AX 


NewHandles 

DW ? 


; Number of Handles needed 
; by this PC DOS 7 process 

ListSize 

EQU (Endofprogram - EntryPoi nt) 

; Number of bytes 

Paragraphs 

EQU (ListSize / lOH) 

; Number of paragraphs 

End_of_program 

LABEL BYTE 


; Last used position for 


this program 


Comments 

The maximum number of file handles allowed for this interrupt is 64KB. If 
the the specified number of allowable handles is less than the current 
number allowed, the specified number will become current only after all the 
handles above the specified number have been closed. If the specified 
number is less than 20, the number is assumed to be 20. Data base 
applications can use this function to reduce the need to swap handles. 

You must release memory for PC DOS 7 to contain the extended handle list. 
You can do this by using the SET BLOCK (4AH) function call. 
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68H — Commit File 


Purpose 

Causes all buffered data for a file to be written to the device. This function 
can be used Instead of a close-open sequence. 


Examples 

MOV 

AH,68H 

; Function Call - Commit File 


MOV 

BX, Handle 

; Select file 


INT 

21H 

; Issue request to DOS 


JC 

Error 

; Error code in AX 


Handle 

DW ? 

; Handle from previous Open or Create 


Comments 

Commit File provides a faster and more secure method of committing data In 
multi-user environments such as the IBM PC Local Area Network Services. 
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6CH — Extended Open/Create 


Purpose 

Optionally opens and creates a file. 


Examples 

MOV AH,6CH 

MOV AL,0 

MOV BX,M0DE 


MOV CX,ATTR 

MOV DX,FLAG 


Extended open 
Reserved 
Open mode 

Format : OWFOOOOOISSSOAAA 
AAA=Access code 0=Read 
l=Wri te 
2=Read/Wri te 

SSS=Sharing mode 0=Compatibility 
l=DenyRead/Wri te 
2=DenyWri te 
3=DenyRead 
4=DenyNone 

I 0=Pass handle to child, l=No inherit 
F 0=INT 24H, l=Return error 
on this open and any I/O to this handle 
W 0=No commit, l=Auto-Commi t on write 
Create attribute (ignored if open) 
Function control, Format=0000000NNNNEEEE 
NNNN=Does not exist action 
0=Fail, l=Create 
EEEE=Exists action 
0=Fail, l=0pen, 2=Repl ace/Open 


MOV SI,SEG file_name ; Name to open or create 
MOV DS,SI 

MOV SI, OFFSET file_name 

INT 21H 

JC ERROR 

; AX=Handle 

; CX=Action taken code 
; l=File Opened 
; 2=File Created/Opened 
; 3=File Replaced/Opened 


Mode 

DW 

7 

; Open mode bit 
; Definitions 

Attr 

DW 

7 

; File attributes 

Flag 

DW 

7 

; Function definition 

Fi le_ 

name 

64 DUP (0) 
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Comments 


Function 6CH combines the functions currentiy avaiiabie with OPEN, CREATE 
and a CREATE NEW. 

If F is 1 , the critical error handler (Interrupt 24) is disabled for the handle 
returned by Extended Open. Any I/O issued to this handle will never 
generate the critical error but only the extended error. 

If F is 0, no actions are taken. 

If W is 1, any disk write using the handle returned by Extended Open will 
accompany with a commit call (see Interrupt 21 FI (AL=68FI)). 

If W is 0, no actions are taken. 
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Appendix C. I/O Control for Devices (lOCtI) 


Purpose 

Sets or gets device information associated with open device handles, or 
sends control strings to the device handle or receives control strings from 
the device handle. 


Comments 

The following function values are allowed In AL: 


AL 

= 

OOH 

AL 

= 

01H 

AL 

- 

02H 

AL 

= 

03H 

AL 

= 

04H 

AL 

= 

OSH 

AL 

= 

06H 

AL 

= 

07H 

AL 

= 

OSH 

AL 

= 

OOH 

AL 

= 

OAH 

AL 

= 

OBH 

AL 

= 

OCH 

AL 

= 

ODH 

AL 

= 

OEH 

AL 

= 

OFH 

AL 

= 

10H 

AL 


11H 


Get device information (returned In DX). 

Set device Information (determined by DX). DH must be 0 for 
this call. 

Read from character device 
Write to character device 
Read from block device 
Write to block device 
Get Input status 
Get output status 

Determine If a particular block device is removable 

Determine if a logical device is local or remote 

Determine if a handle is local or remote 

Change sharing retry count 

Issue handle generic lOCtI request 

Issue block device generic lOCtI request 

Get logical drive 

Set logical drive 

QuerylOCtIHandle 

QuerylOCtIDevice 


lOCtI can be used to get information about devices. You can make calls on 
regular files, but only function values OOH, 06H, and 07H are defined in that 
case. All other calls return an Invalid Function error. 


Function values OOH to OSH are not supported on network devices. Function 
value OBH requires the file sharing command to be loaded (SHARE). 

Many of the function calls return the carry flag clear if the operation was 
successful. If an error condition was encountered, the carry flag is set; AX 
contains an extended error code. (See “Extended Error Codes” on page 138 
in Appendix B for an explanation). An explanation of the error codes for call 
440CH can be located beginning on page 284 in this chapter. Information 
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about the error, such as the error class, location, and recommended action, 
is obtained by issuing the 59H (Get Extended Error) function cali. 


44H — 

I/O Control for Devices (lOCtI) 


Calls AL=00H and AL=01H 


Purpose 


Examples 


These two caiis 

set or get device 

information. 

; To Get Device Information 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,0 

Indicate get device information 

MOV 

BX, Handle 

Select device 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

DevInfo,DX 

Save device information 

; To Set Device Information 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,I 

Indicate set device information 

MOV 

BX, Handle 

Select device 

MOV 

DX, Devinfo 

Device information to set 

XOR 

DH,DH 

All DH bits must be off 

INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 

Devinfo 

DW ? 

Device information 

Handle 

DW ? 

Handle to open device 
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Comments 


The bits of Devinfo are defined as foliows: 



= 0 if this channei is a disk fiie (bits 8 through 15 are 0 in this case). 

Bits 8 through 15 of DX correspond to the upper 8 bits of the device 
driver attribute word. 

If ISDEV = 1 


EOF = 0 if end-of-fiie on input. 

BINARY = 1 if operating in binary mode 
(no checks for Ctri-Z). 

= 0 if operating in ASCII mode 

(checking for Ctri-Z as 

end-of-fiie). 

ISCLK = 1 if this device is the ciock device. 

ISNUL = 1 if this device is the nuii device. 

ISCOT = 1 if this device is the consoie output. 

ISCIN = 1 if this device is the consoie input. 

CTRL = 0 if this device cannot process controi 

strings via calis AL=02H, AL=03H, AL=04H, and AL=05H. 

CTRL = 1 if this device can process controi 
strings via caiis AL=02H and AL=03H. 

Note that this bit cannot be set by 
function caii 44H. 


If ISDEV = 0 

EOF = 0 if channei has been written. Bits 0-5 are the biock device 
number for the channei (0 = A, 1 = B, ...). Bits 15, 8-13, 4 are 
reserved and shouid not be aitered. 
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Note: DH must be 0 for call AL=01H. 


Calls AL=02H, AL=03H 
Purpose 

These two calls allow control strings to be sent or received from a character 
device. 


Examples 


; To Read a Control String from 


MOV 

AH,44H ; 

MOV 

AL,2 ; 

MOV 

BX, Handle ; 

MOV 

CX,SIZE Buffer ; 

MOV 

DI,SEG Buffer ; 

MOV 

DS,DI 

MOV 

DX, OFFSET Buffer ; 

INT 

21H ; 

JC 

Error ; 

MOV 

Count, AX ; 

; To Write a 

Control Stri ng to a 

MOV 

AH,44H ; 

MOV 

AL,3 ; 

MOV 

BX, Handle ; 

MOV 

CX,SIZE Buffer ; 

MOV 

DI,SEG Buffer ; 

MOV 

DS,DI 

MOV 

DX, OFFSET Buffer ; 

INT 

21H ; 

JC 

Error ; 

MOV 

Count, A X ; 

Handle DW 

7 ; 

Buffer DB 

N DUP(?) ; 

Count DW 

7 ; 


a Character Device 

Function Cal 1 - lOCtl 
Indicate lOCtl read 
Select device 
Set size to read 
Address I/O buffer 

DS:DX points to I/O buffer 
Issue request to DOS 
Error code in AX 
Save data read count 

Character Device 

Function Cal 1 - lOCtl 
Indicate lOCtl write 
Select device 
Set size to write 
Address I/O buffer 

DS:DX points to I/O buffer 
Issue request to DOS 
Error code in AX 
Save data written count 


Handle to open device 
I/O buffer 

Actual I/O data transfer count 
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Comments 


These are the Read and Write calls for a character device. An Invalid 
Function error is returned if the CTRL bit is 0. 


Calls AL=04H, AL=05H 
Purpose 

These two calls allow arbitrary control strings to be sent or received from a 
block device. 


Examples 


; To Read a Control String from 


MOV 

AH,44H ; 

MOV 

AL,4 ; 

MOV 

BL, Drive ; 

MOV 

CX,SIZE Buffer ; 

MOV 

DI,SEG Buffer ; 

MOV 

DS,DI 

MOV 

DX, OFFSET Buffer ; 

INT 

2IH ; 

JC 

Error ; 

MOV 

Count, AX ; 

; To Write 

a Control String to a 

MOV 

AH,44H ; 

MOV 

AL,5 ; 

MOV 

BL, Drive ; 

MOV 

CX,SIZE Buffer ; 

MOV 

DI,SEG Buffer ; 

MOV 

DS,DI 

MOV 

DX, OFFSET Buffer ; 

INT 

2IH ; 

JC 

Error ; 

MOV 

Count, AX ; 

Dri ve 

DB ? ; 

Buffer 

DB N DUP(?) ; 

Count 

DW ? ; 


I Block Device 

Function Cal 1 - lOCtl 
Indicate lOCtl read 
Select drive 
Set Size to read 
Address I/O buffer 

DS:DX points to I/O buffer 
Issue request to DOS 
Error code in AX 
Save data read count 

Block Device 

Function Cal 1 - lOCtl 
Indicate lOCtl write 
Select drive 
Set Size to write 
Address I/O buffer 

DS:DX points to I/O buffer 
Issue request to DOS 
Error code in AX 
Save data written count 


Drive (0=current, I=A:, 2=B:, ...) 
I/O buffer 

Actual I/O data transfer count 
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Comments 


These are the Read and Write calls for a block device. The drive number is 
in BL for these calls. An Invalid Function error is returned if the CTRL bit is 
0. An “Access-Denied” code is returned if the drive is invalid. The following 
control strings are defined for block device drivers that support media lock or 
unlock, and eject: 

; Buffer to read drive status (use with lOCtl Read AL=04) 

LockStatus STRUC 

Status_Read db 6 ;Status Read Control block code 

Status_Bits dd ? ; Drive status 

LockStatus ENDS 

The Status_Bits on return, are interrupted as follows: 

Bit 0 0 Door closed 

1 Door open 

Bit 1 0 Door locked 

1 Door unlocked 

Bits 2-31 0 Reserved (all zeros) 

; Buffer to lock or unlock drive (use with lOCtl Write AL=05H) 

LockCommand STRUC 

Lock_Unlock db 1 ;Lock or unlock Control Block Code 

Cmd_Code db ? ;0 for unlock, 1 for lock 

LockCommand ENDS 

; Buffer to eject media (use with lOCtl Write AL=05H) 

EjectCommand STRUC 

Eject db 0 ; Eject Control Block Code 

EjectCommand Ends 

Calls AL=06H and AL=07H 
Purpose 

These calls allow you to check if a handle is ready for input or output. 
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Examples 

; To Get Input Device Status 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,6 

Indicate lOCtl input status 

MOV 

BX, Handle 

Select device 

INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

Status, AL 

Save status 

; To Get Output Device Status 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,7 

Indicate lOCtl output status 

MOV 

BX, Handle 

Select device 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

Status, AL 

Save status 

Handle 

DW ? 

Handle to open device 

Status 

DB ? 

Status 


; for a file: 

; OOH = At End of File 

; FFH = Not at End of File 

; for a device: 

; OOH = Not ready 

; FFH = Ready 

Comments 

If used for a file, AL always returns F2H until end-of-file is reached, then 
always returns OOH unless the current file position is changed through call 
42H. When used for a device, AL returns FFH for ready or 0 for not ready. 

Call AL=08H 


Purpose 

This call allows you to determine if a device can support removable media. 
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Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,8 

Indicate lOCtl is removable 

MOV 

BLjDri ve 

Select drive 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

MOV 

Dtype,AX 

Save type 


Dri ve 

DB 

7 

; Drive (0=current, 1=A:, 2=B 

Dtype 

DW 

7 

; Drive type 


0 = Drive is removable 

1 = Dri ve i s f i xed 
OFH = Drive not valid 


Comments 

If the value returned in AX is 0, the device is removabie. If the value is 1, the 
device is fixed. The drive number should be placed in BL. If the value in BL 
is invalid, an "Access-Denied" is returned. For network devices, the error 
Invalid Function is returned. 

Call AL=09H 
Purpose 

This call allows you to determine if a logical device is associated with a 
network directory. 


Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,9 

Indicate lOCtl is remote drive 

MOV 

BLjDri ve 

Select drive 

INT 

2IH 

Issue request to DOS 

JC 

Error 

Error code in AX 

TEST 

DX,1000H 

See if local /remote 

JNZ 

I s_Remote 

Drive is remote 


DB ? 

Drive (0=current, I=A:, 2=B:, 


280 PC DOS 7 



Comments 


On entry, BL contains the drive number of the biock device you want to 
check (0=defauit, 1=A, 2 = B, and so forth). The vaiue returned in DX 
indicates whether the device is iocai or remote. Bit 12 is set for remote 
devices (1000H). Bit 12 is not set for iocai devices. The other bits in DX are 
reserved. If disk redirection is paused, the function returns with bit 12 not 
set. 

Call AL=0AH 


Purpose 


Examples 


This cali aiiows you to determine if a handle is for a iocai device or a remote 


device across the network. 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,0AH 

Indicate lOCtl is remote handle 

MOV 

BX, Handle 

Select device/file 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

TEST 

DX,8000H 

See if local /remote 

JNZ 

I s_Reniote 

Drive is remote 

Handle 

DW ? 

Handle to open file or device 


Comments 

For remote devices, bit 15 is set (8000H). The handie shouid be placed in BX. 
Bit 15 is not set for iocai devices. 


Call AL=0BH 


Purpose 

This cail controis retries on sharing and iock resource confiicts. 
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Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,0BH 

Indicate lOCtl set retry counts 

MOV 

CX, NumLoops 

Set number of loops 

MOV 

DX, NumRetri es 

Set number of retries 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 


NumLoops DW 

NumRetri es DW 


; Number of times to execute loop below 
; Number of times to retry on error 


Comments 

All sharing and lock conflicts are automatically retried a number of times 
before they are returned as a PC DOS 7 error or critical error. You can 
select the number of retries and the delay time between retries. On Input, 
CX contains the number of times to execute a delay loop, and DX contains 
the number of retries. The delay loop consists of the following sequence: 

XOR CX,CX 

LOOP $ ;spin 64K times 

If this call Is not Issued, PC DOS 7 uses delay=1 and retrles=3 as the 
defaults for CX and DX. If you expect your application to cause sharing or 
lock conflicts on locks that are in effect for a short period of time, you may 
want to increase the values for CX and DX to minimize the number of errors 
actually returned to your application. 

Call AL = OCH 
Purpose 

This generic lOCtI function uses an open device handle to request a device 
driver to perform code page switching or to get/set device information. 

Examples 


MOV 

AH,44H 

MOV 

AL,0CH 

MOV 

BX, Handle 

MOV 

CH, Category 

MOV 

CL, Function 

MOV 

DI,SEG Packet 


Function Cal 1 - lOCtl 

Indicate file handle generic lOCtl request 
Select device/file 
Set device type 
Set function 

Address subfunction parameter packet 
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MOV 

DS,DI 


MOV 

DX, OFFSET Packet 

DS:DX points to parameter packet 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 


Handle DW ? 

Category DB ? 


Function DB 


Handle to open file or device 
Type of Device 

0 - Unknown (if device type not known) 

1 - a COMx devi ce 
3 - CON 

5 - a LPTx device 
Function within category 
For category 3 & 5: 

4CH = Prepare start 
4DH = Prepare end 
4AH = Select (Set) code page 
6AH = Query (Get) selected code page 
6BH = Query prepare list 
For Category 3: 

5FH = Set display information 
7FH = Get display information 


Prepare Start: When CL=4CH, the parameter block, pointed to by DS:DX, 
has the following layout: 


Packet 

Label 


Word 

PS PACKET 

STRUC 


Prepare start packet 

PS_FLAGS 

DW 

0 

Control flags 

; Bit 0 = 0 : Download prepare 
; BIT 0=1: Cartridge prepare 
; Others reserved (set to 0) 

PS LENGTH 

DW 

(n+l)*2 

Length of rest of packet in bytes 

PS NUMCP 

DW 

n 

Number of code pages 

PS CPI 

DW 

7 

Code page 1 


PS CPn 

DW 

7 

; Code page n 

PS_PACKET 

ENDS 
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Notes: 

1. Setting any PS_CPn to -1 tells the device driver not to change the code 
page value for that position. Any other value is a code page to be 
prepared. 

2. n is the number of additional code pages specified in the DEVICE^ 
command in CONFIG.SYS. The value for n can be up to 12. 

3. For cartridge-prepares set the PS_FLAGS field to 1. 

A Prepare Start request begins the preparation of a code page. It is followed 
by writing data defining the code page font to the device driver using one or 
more lOCtI write control string calls (AX=4403FI). It is assumed that this 
information will be downloaded to the device. The stream is ended by a 
Prepare End. The format of the stream is device dependent. 

If the information is lost (due to a system failure or power-off), you do not 
have to rewrite the prepared code page. Requesting a "refresh" operation 
by issuing a Prepare Start to the device driver with all code page values 
(PS_CPn) set to a negative one (-1), restores the most recently prepared 
code page information to the device. You must follow this operation 
immediately with a Prepare End. 

If no data is written for a prepare operation, the driver interprets the newly 
prepared code page(s) as a hardware code page. This allows devices that 
support user changeable hardware fonts (usually in cartridges) to be 
supported. 

No prepare is needed for hardware-defined code pages. 

Prepare Start Error Codes 


Code 

Meaning 


01 

Invalid function number 


22 

Unknown command 


27 

Code page conflict (used for 

KEYBxx mismatch) 

29 

Device error 


31 

Device driver does not have 

device 

copy of code page to download to 


Write Error Codes 
Code Meaning 

27 Device not found in file, or code page not found in file 

29 Device error 

31 File contents not a font file, or file contents structure damaged 
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Prepare End: When CL=4DH the parameter block, pointed to by DS:DX, has 
the following layout: 


Packet 

Label Word 


PE PACKET 

STRUC ; 

Prepare end packet 

PE LENGTH 

DW 2 ; 

Length of packet in bytes 

PE RESVl 

DW 0 ; 

(Reserved, must be 0) 

PE PACKET 

ENDS 


Prepare End Error Codes 


Code 

Meaning 


19 

Ead data read from font file 

31 

No prepare start 



Select/Query Selected Code Page: When CL=4AH or 6AH the parameter 
block, pointed to by DS:DX, has the following layout: 


PACKET LABEL WORD 

CP PACKET STRUC 

CP LENGTH DW 

2+(n+l)*2 

; Select/Query Selected packet 
; Length of packet in bytes 

CP CPID 

DW 

7 

; Code page ID 

CP_VECT0R1 

DB 

? ? 

• J • 

; DBCS vectorl 

CP_VECT0Rn 

DB 

? ? 

• J • 

; DBCS Vectorn 

CP_PACKET 

ENDS 

DB 

0,0 ; End marker 


Select/Query Selected Code Page also includes the DECS environment 
vector. Some device drivers may support only the code page value. As a 
result, you must check the returned length when using this call to determine 
if the DECS information is present. Only the drivers supplied with the Asian 
version of PC DOS 7 provide this support. 

Select Code Page Error Codes 

Code Meaning 

26 Code page not prepared 

27 Current keyboard does not support this code page 

29 Device error 

Ouery Selected Code Page Error Codes 
Code Meaning 

26 No code page has been selected 

27 Device error 
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Query Prepared List: When CL=6BH, the parameter block, pointed to by 
DS:DX, has the following layout: 


PACKET LABEL 

QL_PACKET STRUC 

QL_LENGTH DW((m+l)+(n+l) )*2 
QLJUMHWCP DW n 

QL_HWCP1 DW ? 


WORD 

; Query list packet 
; Length of packet in bytes 
; Number of hardware code pages 
; Hardware code page 1 


QL HWCPn 

DW 

7 

; Hardware code page n 

QL NUMCP 

DW 

n 

; Number of prepared code pages 

QL CPI 

DW 

7 

; Prepared code page 1 


QL CPm 

DW ? 

; Prepared code page n 

QL_PACKET 

ENDS 



Note: The device driver may return up to 12 code page values for each type 
of code page (hardware or prepared) so n can be up to 12, and m can 
be up to 12. 

Query Prepared List Error Codes 
Code Meaning 

26 No code pages have been selected 

29 Device error 


Get/Set Display Information: When CL=5FH or 7FH, the parameter block, 
pointed to by DS:DX, has the following layout: 


VP_PACKET STRUC 
VP_LEVEL DB 0 

VP_RESV1 DB 0 
VP_LENGTH DW 14 
VP FLAGS DW 0 


VP MODE DB ? 


VP RESV2 DB 0 


; Video parameters packet 
; Requested info level (set to 0 before lOCtl 
; Call) 

; (Reserved, must be 0) 

; Length of rest of packet in bytes 
; Control flags 
; Bit 0 = 0 : Intense colors 
; Bit 0 = 1 : Blink 
; Others reserved (set to 0) 

; Video mode 
; 1 = Text 
; 2 = APA 
; Others reserved 
; (Reserved, must be 0) 
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VP_COLORS DW ? 
VP_WIDTH DW ? 
VP_LENGTH DW ? 
VP_COLS DW ? 
VP_ROWS DW ? 

VP PACKET ENDS 


Number of colors (Mono=0) 

Display width in pixels (APA mode only) 
Display length in pixels (APA mode only) 
Display width in characters 
Display length in characters 


Call AL = ODH 


Purpose 

This generic lOCtI function requests a block device driver to perform one of 
the following subfunctions: 

• Get device parameters 

• Set device parameters 

• Read track on logical device 

• Write track on logical device 

• Format and verify track on logical device 

• Verify track on logical device 

• Get access flag status 

• Set access flag status. 

Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 


MOV 

AL,0DH 

Indicate Block Device Generic 

lOCtl 

MOV 

BLjDri ve 

Select Device/File 


MOV 

CH, Category 

Set Device Type 


MOV 

CL, Function 

Set Function 


MOV 

DS,SEG Packet 

Address Subfunction Parameter 

Packet 

MOV 

DX, OFFSET Packet 



INT 

21H 

Issue request to DOS 


JC 

Error 

Error code in AX 


Dri ve 

DB ? 

Drive (0=current, 1=A:, 2=B:, 

...) 

Category 

DB ? 

Type of Device 

8 - Block Device 


Functi on 

DB ? 

Function within Category 

For Category 8: 




40H = Set device parameters 
60H = Get device parameters 
41H = Write track on logical 

devi ce 



61H = Read track on logical 

devi ce 
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; 42H = Format and verify track on 

; logical device 

; 62H = Verify track on logical device 

; 47H = Set access flag 

; 67H = Get access flag 

; 68H = Get media type 

Note: Functions 43H through 46H and functions 63H through 66H are 
reserved for the system. 


Comments 

CH contains the major code (OSH for aii functions) and CL contains the minor 
code (function). 

Get or Set Device Parameters 

To Get Device Parameters, set CL = 60H. 

To Set Device Parameters, set CL = 40H. 

When CL = 60H or CL = 40H, the parameter biock has the foiiowing fieid 
iayout: 

Packet 

A_devi ceParameters 
Special Functions 
Devi ceType 
DeviceAttributes 
NumberOfCyl i nders 
Medi aType 
Devi ceBPB 
TrackLayout 
A_devi ceParameters 

An expianation of each field in the parameter block is given in the pages that 
follow. 


Label Byte 

STRUG 
DB ? 

DB ? 

DW ? 

DW ? 

DB ? 

a_BPB <> 
a_TrackLayout <> 
ends 


SpecialFunctions Field 

This 1-byte field is used to further define the Get and Set Device Parameters 
functions. 

For the Get Device Parameters function, bit 0 of the SpecialFunctions field 
has the follewing meaning: 

Bit 0 =1 Return the BPB that BUILD BPB would return. 

=0 Return the default BPB for the device. 

Note: All other bits must be off. 
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For the Set Device Parameters function bits 0, 1, and 2 of the 

SpecialFunctions field are used. 

These bits have the following meanings when CL = 40H. 

Bit 0 =1 All subsequent BUILD BPB requests return DeviceBPB. If 

another Set Device request Is received with bit 0 reset, BUILD BPB 
returns the actual media BPB. 

=0 Indicates that the DeviceBPB field contains the new default 
BPB for this device. If a previous Set Device request set this bit 
on, the actual media BPB Is returned. Otherwise, the default BPB 
for the device is returned by BUILD BPB. 

Bit 1 =1 Ignore all fields In the Parameter Block except the TrackLayout 

field. 

=0 Read all fields of the parameter block. 

Bit 2 =1 Indicates that all sectors In the track are the same size and all 

sector numbers are between 1 and n (where n is the number of 
sectors in the track.) 

=0 Indicates that all sectors In the track may not be the same size. 

Notes: 

1. All other bits must be reset. 

2. Set bit 2 for normal track layouts. Format Track can be more efficient if 
bit 2 is set. 

3. Setting bits 0 and 1 at the same time is invalid and should be considered 
an error. 

DeviceType Field 

This 1-byte field describes the physical device type. Device type is not set by 
lOCtI but is received from the device. 

The values in this field have the following meanings: 

0 = 320/360 KB 5.25 inch 

1 = 5.25 inch, 1.2 MB 

2 = 3.5 inch, 720 KB 

3 = 8-inch single-density 

4 = 8-inch double-density 

5 = Hard disk 

6 = Tape drive 

7 = 3.5 inch, 1.44 MB 

8 = Read/Write Optical devices 

9 = 3.5 inch, 2.88 MB 
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DeviceAttributes Field 

A 1-word field that describes the physical attributes of the device. Device 
attributes are not set by lOCtI but are received from the device driver. 

Only bits 0 and 1 of this field are used. They have the following meanings: 

Bit 0 =1 media is not removable. 

=0 media is removable. 

Bit 1 =1 diskette changeline is supported. 

=0 diskette changeline is not supported. 

Bits 2-15 are reserved. 

NumberOfCylinders Field 

This field indicates the maximum number of cylinders supported on the 
physical device, independent of the media type. The information in this field 
is not set by lOCtI, but is received from the device driver. 

MediaType Field 

For multimedia drives, this field indicates which media is expected to be in 
the drive. This field is only meaningful for Set Device Parameters (CL = 
40H) subfunction. 

The MediaType field is used only when the actual media in the drive cannot 
otherwise be determined. Media type is dependent on device type. 

Regardless of the device type, a value of 0 represents the default. For 
example, a 5.25-inch 1.2MB diskette drive is a multimedia drive. The media 
type is defined as follows: 

0 = Quad density 1.2 MB (96 tpi) diskette 

1 = Double density 320/360KB (48 tpi) diskette 

The default media type for a 1.2MB drive is a quad density 1.2 MB diskette. 

DeviceBPB Field 

For the Get Device Parameters function: 

• If bit 0 of the SpecialFunctions field is set, the device driver returns the 
BPB that BUILD BPB would return. 

• If bit 0 of the SpecialFunctions field is not set, the device driver returns 
the default BPB for the device. 

For the Set Device Parameters function: 
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• If bit 0 of the SpecialFunctions field is set, the device driver is requested 
to return the BPB from this field for all subsequent BUILD BPB requests 
until a Set Device Parameters request is received with bit 0 in the 

SpecialFunctions field reset. 

• If bit 0 is not set, the BPB contained in this field becomes the new default 
BPB for the device. 

The DeviceBPB field has the following format: 

a_BPB STRUC 

BytesPerSector DW 

SectorsPerCl uster DB 

ReservedSectors DW 

NumberOfFATs DB 

RootEntries DW 

Total Sectors DW 

MediaDescriptor DB 

SectorsPerFAT DW 

9 

SectorsPerTrack DW 

Heads DW 

HiddenSectors DD 

BigTotal Sectors DD 

Reserved DB 

a BPB ENDS 


TrackLayout Field 

This is a variable length table indicating the expected layout of sectors on 
the media track. 

PC DOS 7 device drivers do not keep a track layout table for each logical 
device. The global track table must be updated (by the Set Device 
Parameters subfunction) when the attributes of the media change. 

Note: The Set Device Parameters subfunction (CL=40H) modifies the track 
table regardless of how bit 1 of the SpecialFunctions field is set. 

For Get Device Parameters, this field is not used. The track layout is used by 
subsequent Read/Write Track, Format/Verify Track and Verify Track 
functions. 

The following example shows how this field is formatted: 


7 

7 

7 

7 

7 

7 

7 

7 

7 

7 

7 

7 

6 Dup (0) 
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Total sectors 

SectorCount 

DW 

n 

Sector 

1 

SectorNumber 1 

DW 

IH 



SectorSize_l 

DW 

200H 

Sector 

2 

SectorNumber 2 

DW 

2H 



SectorSize_2 

DW 

200H 

Sector 

3 

SectorNumber 3 

DW 

3H 



SectorSize_3 

DW 

200H 

Sector 

4 

SectorNumber 4 

DW 

4H 



SectorSize_4 

DW 

200H 

Sector 

n 

SectorNumber n 

DW 

n 



SectorSize n 

DW 

200H 


Note: All values are In hexadecimal. 


The total number of sectors Is Indicated by the SectorCount field. Each sector 
number must be unique and in a range between 1 and n (sector count). As 
shown In the example above, the first sector number Is 1 and the last sector 
number Is equal to the sector count (n). If bit 2 of the SpecialFunctions field 
Is set, all sector sizes, which are measured in bytes, must be the same. 

See the description of bit 2 under the SpecialFunction field. 

Note: The DeviceType, DeviceAttributes, and NumberOfSectors fields should 
be changed only If the physical device has been changed. 

Read/Write Track on Logical Device 

To read a track on a logical device, set CL = 61 H. 

To write a track on a logical device, set CL = 41 H. 

The parameter block has the following layout when reading or writing a track 
on a logical device. 


Packet 

LABEL 

BYTE 

a_ReadWri teTrackPacket 

STRUC 


Special Functions 

DB 

7 

Head 

DW 

7 

Cyl i nder 

DW 

7 

Fi rstSector 

DW 

7 

NumberOfSectors 

DW 

7 

TransferAddress 

DD 

7 
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A_ReadWri teTrackPacket ENDS 

Notes: 

1. All bits in the SpecialFunctions field must be reset. 

2. The value in the FirstSector field and the NumberOfCylinders field Is 
0-based. For example, to Indicate sector 9, set the value to 8. 

Format/Verify Track on Logical Drive (lOCtI Write) 

To format and verify a track, set CL = 42H. 

To verify a track, set CL = 62H. 

The parameter block has the following layout when formatting a track or 
verifying a track on a logical drive. 


PACKET 

LABEL 

BYTE 

A_Forniat Packet 

STRUC 


Special Functions 

DB 

7 

Head 

DW 

7 

Cyl i nder 

DW 

7 

A FormatPacket 

ENDS 



On entry, bit 0 of the SpecialFunctions field has the following meanings: 

Bit 0 = 1 Format status check call to determine If a 
combination of number-of-tracks and 
sectors-per-track is supported. 

= 0 Format /Verify track call. 


To determine If a combination of number-of-tracks and sectors- per-track Is 
supported, a Set Device Parameters call must be Issued with the correct BPB 
for that combination before issuing the Format Status call. The device driver 
can then return the correct code to Indicate what Is supported. The value 
returned in the SpecialFunctions field for a Format Status Check call are: 

0 = This function is supported by the 

ROM BIOS. The specified combination of 
number-of-tracks and sectors-per-track is 
allowed for the diskette drive. 

1 = This function is not supported by 

the ROM BIOS. 
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= This function is supported by the 
ROM BIOS. The specified combination of 
number-of-tracks and sectors-per-track is 
not allowed for the diskette drive. 


3 = This function is supported by the 

ROM BIOS, but ROM BIOS cannot determine 
if the numbers-of-tracks and 
sectors-per-track are allowed because 
the diskette drive is empty. 

To format a track: 

1. Issue the Set Device Parameters function call. 

2. Issue the Format Status Check function call to validate the 
number-of-tracks and sectors-per-track combination. Ignore the result if 
the value returned is 1, because the ROM BIOS does not support this 
function. 

3. Issue the Format/Verify Track function call with the SpecialFunctions bit 0 
reset for each track on the medium. 

Get/Set AccessFlag Status 

To get the access flag status of a hard disk, set CL=67FI. 

To set the access flag status of a hard disk, set CL=47FI. 

The parameter block has the following layout when getting or setting the 
access flag status of a hard disk: 

PACKET LABEL 

a_DiskAccess_Control STRUC 

SpecialFunctions DB 0 

DiskAccess_Fl ag DB ? 

a_DiskAccess_Control ENDS 

If the media has not been formatted or has an invalid boot record, the system 
will not allow disk I/O for the media. This ensures data integrity of fixed 
media. Since formatting a media is a special activity, and is needed to 
perform disk I/O for unformatted media, additional functions to control the 
disk access flag are necessary. A format utility should issue "Set the access 
flag status (CL=47FI)" with DiskAccess_Flag = non-zero value to access the 
unformatted media. When every format operation is a success, leave the 
access flag status as it is to allow further disk I/O from general users. If 


BYTE 

; 0 = Disallow disk access 
; Other value = allow disk access 
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format fails, issue "Set the access flag status (CL = 47H)" with 
DiskAccess_Flag = zero in order te block further media access. To get the 
current status of the system disk access flag, issue "Get the access flag 
status (CL = 67H)". If DiskAccess Flag = zero, disk I/O is not allowed for 
the media. 

Get/Set Media ID 

To get the media ID, set CL=66H. 

To set the media ID, set CL=46H. 

The parameter block has the following layout when getting and setting the 
media ID: 


PACKET 

Medi a_ID_Pacl<et 

LABEL 

STRUC 

BYTE 


Info_Level 

DW 

0 

Information level, 
currently always 0 

Seri al 

DD 

7 

Volume serial number 

Label 

DB 

11 dup (' 

Volume label from 
boot record 

File_Sys_Type 

Media ID Packet 

DB 

ENDS 

8 dup (' ') 

File system type 


Get Media ID cepies the information from the boot record into the 
Media_ID_Packet. Set Media ID cepies the infermation from the 
Media_ID_Packet to the boot record. If the disk does not contain a valid 
BPB, or the signature field is missing, then no action is taken, and beth 
functions return Unknewn Media (error code 7). 

Get Media Type (PC DOS 7) 

To get the media type, set CL=68H. 

The parameter bleck has the following layout: 


PACKET 

Medi a_Type_Packet 

LABEL 

STRUC 

BYTE 


Defaul t 

DB 

7 

1 if media is equal or equivalent 
to the capacity of the drive. 

0 i f medi a is 1 ess than 
the capacity of the drive. 

Medi a_Type 

DB 

7 

Media Type: 

2 for 720KB 3.5-inch 80-track floppy 

7 for 1.44MB 3.5-inch 80-track floppy 
9 for 2.88MB 3.5-inch 80-track floppy 

Reserved_l 

DB 

7 

Reserved 

Reserved_2 

DD 

7 

Reserved 
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Medi a_Type_Pacl<et 


ENDS ? 


Comments 

If carry is set, then the error return code is in AX. Otherwise, carry is 
cieared. 

Call AL = OEH Get Logical Drive Map 
Purpose 

This cali aiiows the device driver to determine if more than one iogicai drive 
is assigned to a biock device. When this cail is issued, a drive number is 
passed in BL on input. 


Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,0EH 

Indicate Logical Drive Check 

MOV 

BLjDri ve 

Select Drive 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

CMP 

AL,0 

Only one drive letter for this device? 

JE 

Singl e_Dri ve 

Yes! 

MOV 

Acti veDri ve,AL 

Save Active Drive info 


Dri ve DB ? 

ActiveDrive DB ? 


; Drive (0=current, 1=A:, 2=B:, ...) 

; Current drive letter for this device 
; (1=A:, 2=B:, ...) 


Comments 

If the block device has more than one logical drive letter assigned to it, on 
output a drive number corresponding to the last drive letter that was used to 
reference the device is returned in AL. If only one drive letter is assigned to 
the device, 0 is returned in AL by this call. 
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Call AL = OFH Set Logical Drive Map 


Purpose 

This call requests the device driver to change the next logical drive letter 
that will be used to reference a block device. 


Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,0FH 

Indicate Set Logical Drive 

MOV 

BLjDri ve 

Set Drive 

INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 

CMP 

AL,0 

Only one drive letter for this device? 

JE 

Singl e_Dri ve 

Yes! 

MOV 

Acti veDri ve,AL 

Save Active Drive info 
(should be the same as BL in) 


Dri ve DB ? 

ActiveDrive DB ? 


; Drive (0=current, 1=A:, 2=B:, ...) 

; Current drive letter for this device 
; (1=A:, 2=B:, ...) 


Comments 

When copying diskettes on a drive whose physical drive number has more 
than one logical drive letter assigned to it (for example, copying on a single 
drive system), PC DOS 7 Issues diskette swap prompts to tell you which 
logical drive letter Is currently referencing the physical drive number. As the 
drive changes from source to target, PC DOS 7 issues the message: Insert 
diskette for drive X: and strike any key when ready. 

It Is possible to avoid this message by Issuing call AL = OFH (Set Logical 
Drive). 

To avoid the PC DOS 7 diskette swap message, set BL to the drive number 
that corresponds to the drive letter that will be referenced In the next I/O 
request. 

Note: You can determine the last logical drive letter assigned to the physical 
drive number by issuing call AL = OEH. 
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Because any bleck device can have logical drives, this call should be issued 
before all I/O operations involving more than one drive letter; otherwise, the 
PC DOS 7 message may be issued. 

Call AL = 10H Query lOCTL Handle 
Purpose 

QuerylOCtlHandle accepts a device handle and determines whether a 
specific lOCtI capability is supported by the device. 


Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,10H 


MOV 

BX, handle 

Select device/file 

MOV 

CH, category 

Category function 

MOV 

CL, function 

Packet filled in for function 
to be tested 

MOV 

DX, offset packet 


INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 


Comments 

Category, function, and parameter block are filled in as they would be for the 
function whose presence is being checked for. 

Upon exit, if carry is set, the error code in AL will be 1 for “Function not 
supported.” If carry is not set, then AX = 0. 

This function call is supported by DOS 5.0 device drivers. 

Call AL = 11 H Query IQCTL Device 
Purpose 

QuerylOCtlDevice accepts a drive number and determines whether a specific 
lOCtI capability is supported by the drive. 
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Examples 


MOV 

AH,44H 

Function Cal 1 - lOCtl 

MOV 

AL,11H 


MOV 

BLjdri ve 

Select drive 

MOV 

CH, category 

Category function 

MOV 

CL, function 

Packet filled in for function 
to be tested 

MOV 

DX, offset packet 


INT 

21H 

Issue request to DOS 

JC 

Error 

Error code in AX 


Comments 

Category, function, and parameter block are filled in as they would be for the 
function whose presence is being checked for. 

Upon exit, if carry is set, the error code in AL will be 1 for “Function not 
supported.” If carry is not set, then AX = 0. 

This function call is supported by DOS 5.0 device drivers. 
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Appendix D. Expanded Memory Support 


Expanded memory is memory addressable through a combination of an 
Expanded Memory Specification (EMS) device driver and an EMS-capable 
hardware adapter or via a 386 memory manager. 


The table below lists the Lotus/Intel/Microsoft (LIM) Expanded Memory 
Manager Specification Version 4.0 functions. 


LIM 

INT 67H 

Interface 

Description 

Function 

1 

AH 


40H 

Basic 

Get status 

2 

AH 


41 H 

Basic 

Get page frame address 

3 

AH 


42H 

Basic 

Get unallocated page count 

4 

AH 


43H 

Basic 

Allocate pages 

5 

AH 


44H 

Basic 

Map/unmap handle page 

6 

AH 


45H 

Basic 

Deallocate pages 

7 

AH 


46H 

Basic 

Get EMM version 

8 

AH 


47H 

Advanced 

Save page map 

9 

AH 


48H 

Advanced 

Restore page map 

10 





Reserved 

11 





Reserved 

12 

AH 


4BH 

Advanced 

Get EMM Handle count 

13 

AH 

= 

4CH 

Advanced 

Get EMM Handle pages 

14 

AH 


4DH 

Advanced 

Get all EMM handle pages 

15 

AH 


4EH 

Advanced 

Get/Set page map 

16 

AH 

= 

4FH 

Advanced 

Get/Set partial page map 

17 

AH 


50H 

Advanced 

Map/Unmap multiple handle pages 

18 

AH 


51 H 

Advanced 

Reallocate pages 

19 

AH 


52H 

Advanced 

Get/Set handle attributes 

20 

AH 


53H 

Advanced 

Get/Set handle name 

21 

AH 


54H 

Advanced 

Get handle directory 

22 

AH 


55H 

Advanced 

Alter page map and jump 

23 

AH 


56H 

Advanced 

Alter page map and call 

24 

AH 


57H 

Advanced 

Move/Exchange memory region 

25 

AH 

= 

58H 

Advanced 

Get mappable physical address 
array 

26 

AH 

= 

59H 

Advanced 

Get expanded memory hardware 
information 

27 

AH 

= 

5AH 

Advanced 

Allocate new pages 

28 

AH 

= 

5BH 

Advanced 

Alternate page map register set 

29 

AH 

= 

5CH 

Advanced 

Prepare expanded memory 
hardware for warm boot 

30 

AH 

= 

5DH 

Advanced 

Enable/Disable Operating System 
Environment function set 
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The following pages only outline the basic functions of the Expanded Memory 
Specification, these functions being the ones useful to application 
developers. 

For Information on the advanced functions, more detailed Information and 
guidelines on the use of these calls, refer to the Expanded Memory 
Specification published by Lotus/Intel/Microsoft. 
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Function 1 — Get Status 


Purpose 

This function returns the status that teiis yeu whether the EMM386 is present 
and if the hardware is working correctiy. This function does net require a 
previousiy opened EMM handie. 

Examples 


MOV 

AH, 40H 

; Function to Get Status 

INT 

67H 

; Call Interrupt 67H 

OR 

AH, AH 


JNZ 

error handler 



Comments 

A return cede of 0 in the AH register is for a successfui cail. The foiiowing is 
a list ef other possibie codes. 

AH Description 

OOH The memory manager is loaded and the hardware is working. 

80H The manager detected a problem in the EMM software. 

81 H The manager detected a problem in the expanded memory 

hardware. 

84H The function code passed to the EMM is not defined. 
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Function 2 — Get Page Frame Address 


Purpose 

This function informs your program where the page frame is iocated. it 
returns the segment portien of the page frame address in the BX register. 
This function does not require a previousiy opened EMM handie. 


Examples 

MOV 

AH, 41H 

; Get Page Frame Address function 


INT 

67H 

; Call interrupt 67H 


OR 

AH, AH 



JNZ 

error_handler 



MOV 

Page_Segment, BX 



Page_Segment DW ? 

; Page Segment Address 

Comments 





A return code of 0 in the AH register is for a successfui cail. The foiiowing is 
a iist of other pessibie cedes. 


AH 

Description 

OOH 

The memory manager is loaded and the hardware is working. 

80H 

The manager detected a problem in the EMM software. 

81H 

The manager detected a problem in the expanded memory 


hardware. 

84H 

The function code oassed to the EMM is not defined. 


The BX register contains the segment address of the page frame. The vaiue 
in BX has no significance if AH is not equai to 0. 
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Function 3 — Get Unallocated Page Count 


Purpose 

This function informs your program the number of unaiiocated pages and the 
totai number of pages in expanded memory. This function does not require a 
previousiy opened EMM handie. 


Examples 

MOV AH,42H ; Get Unallocated Page count 

INT 67h ; Call Interrupt 67H 

OR AH, AH 

JNZ error_handler 

MOV UNAl located_Pages,BX ; Store UnAl located pages 

MOV Total_Pages,DX ; Store Total Pages 

UnAl located_Pages DW ? ; Number of Unallocated Pages 

Total_Pages DW ? ; Total Number of Pages 

Comments 

A return code of 0 in the AH register is for a successfui cail. The foiiowing is 
a list of other possible codes. 


AH 

Description 

OOH 

The memory manager is loaded and the hardware is working. 

80H 

The manager detected a problem in the EMM software. 

81H 

The manager detected a problem in the expanded memory 
hardware. 

84H 

The function code nassed to the EMM is not defined. 

The BX register has the following meaning: 

BX 

Description 

OOH 

All pages in expanded memory have already been allocated. 

None are currently available for expanded memory. 

< > OOH 

The number of pages that are currently available. 


The DX register if not equal to 0 contains the total number of pages in 
expanded memory. 
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Function 4 — Allocate Pages 


Purpose 

This function aiiocates the number of pages your program requests and 
assigns a unique EMM handie to these pages. The EMM handie "owns" 
these pages untii your program iater deaiiocates them. 

Examples 

MOV AH,43H 

MOV BX,Number_Pages 

INT 67H 

OR AH, AH 

JNZ error_handler 

MOV EMM_Handle, DX ; Store EMM Handle 

Number_Pages DW ? ; Number of Pages to Allocate 

EMM_Handle DW ? ; EMM Handle 

Comments 

The status is returned in register AH and has the foiiowing meanings: 

AH Description 

OOH The manager has allocated the pages to an assigned EMM 

handle. 

80H The manager detected a problem in the EMM software. 

81 H The manager detected a problem in the expanded memory 

hardware. 

84H The function code passed to the EMM is not defined. 

85H All of the EMM handles are being used. 

87H There is not enough expanded memory pages to satisfy your 

program's request. 

88H There is not enough unallocated pages to satisfy your 

program's request. 

89H Can not allocate zero pages. 

The DX register centains a unique EMM handle. The program must use this 
EMM handle (as a parameter) in any subsequent function calls that map or 
deallocate expanded memory. 


Allocated Pages Function 
Number of Pages to Allocate 
Call Interrupt 67H 
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Function 5 — Map Handle Page 


Purpose 

This function iets your program access the information stored in a iogicai 
page at a physicai page within the page frame. 


Examples 


MOV 

MOV 


MOV 

MOV 

INT 

OR 

JNZ 


DX,EMM_Handle 

BX,Logical_Page 


Previously Opened EMM Handle 
(Function 4 - Allocate Pages) 
Logical Page in the Physical 
Page Within the Page Frame 
Range is 0 to total pages 
allocated to a Handle -1 


AL, Physical Page 

AH,44H 

67H 

AH, AH 

error handler 


; Range is 0 to 3 
; function to Map Handle Page 
; Call Interrupt 67H 


Comments 

The function returns one of the foiiowing status codes: 


AH 

Description 

OOH 

The manager has mapped the page. The page is now ready to 
be accessed. 

80H 

The manager detected a problem in the EMM software. 

81H 

The manager detected a problem in the expanded memory 
hardware. 

83H 

Invalid EMM handle specified. 

84H 

The function code passed to the EMM is not defined. 

8AH 

The logical page is out of range of the logical pages which are 
allocated to this EMM handle. 

8BH 

The physical page at which the logical page was supposed to be 
maooed is out of the ranoe of ohvsical oaoes. 
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Function 6 — Deallocate Pages 


Purpose 

This function deallocates the pages currently allocated to an EMM handle. 
After your program Invokes this functlen, ether application programs can use 
these pages. 

Warning 

Your program should invoke this functien before it exits to DOS. If it does 
not, other programs may not use these pages or their handle. 


Examples 


MOV 

OX, EMM_handle 

; Previously Opened EMM Handle 
; (Function 4 - Allocate Pages) 

MOV 

AH, 45h 

; Deallocate Pages Function 

INT 

67h 

; Call Interrupt 67H 

OR 

AH, AH 


JNZ 

error handler 



Comments 

The following status is returned in the AH register: 


AH 

Description 

OOH 

The manager has deallocated the pages previously allocated to 
the EMM handle. 

80H 

The manager detected a problem in the EMM software. 

81H 

The manager detected a problem in the expanded memory 
hardware. 

83H 

Invalid EMM handle specified. 

84H 

The function code passed to the EMM is not defined. 

86H 

The EMM detected a "save" or "restore" page mapping context 
error (FUNCTION 8 or 9). There is a page mapping register 
state in the "save area" for the EMM handle specified. Save 

Page Map (FUNCTION 8) placed it there and it has not been 
removed by a subsequent Restore Page Map (FUNCTION 9). 


You need to restore the contents of the page mapping register 
before vou deallocate the EMM handle's oaoefsi. 
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Function 7 — Get EMM Version 


Purpose 

This function returns the version number of the Expanded Memory Manager 
software. 


Exampies 


MOV AH,46H 

INT 67H 

OR AH, AH 

JNZ error_handler 

MOV EMM_Version,AL ; Store Version Information 


Comments 

The function returns one of the foiiowing status vaiues: 


AH 

Description 

OOH 

The manager is present in the system and the hardware is 


working correctly. 

80H 

The manager detected a problem In the EMM software. 

81H 

The manager detected a problem In the expanded memory 


hardware. 

84H 

The function code nassed to the EMM is not defined. 


The AL register contains the Expanded Memory Manager's version number 
in Binary Coded Decimai. The upper four bits in the AL register contain the 
integer digit (3.x) of the version number. The iower four bits in the AL 
register contain the fractionai digit of (x.2) version number. The vaiue 
contained in AL has no importance if AH is not equai to 0. 
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Detecting the Expanded Memory Manager 

In this brief section we show an exampie of how you may detect the 
presence of an instaiied Expanded Memory Manager. The first method uses 
the DOS iNT 21 H function SDH (Open a Fiie), which is used to open a fiie or 
device. 

The EMM driver is opened using its name EMMXXXXO, if the open is 
successfui, it means that either an EMM driver is instaiied or that a fiie 
named EMMXXXXO exists on the defauit drive and directory. The iatter case 
is uniikeiy, but you shouid check for the possibiiity. This is done by using 
DOS INT 21 H function 44H, subfunction 07H (iOCti, Get Output Status). The 
handie returned from the Open Fiie function is used with the IOCti, Get 
Output Status - this subfunction checks the output status of a device that is 
associated with a handie. If the return of this subfunction is OOH, then the 
device is actuaiiy a disk fiie and EMM is not instaiied or available. If the 
return is FFH then the opened handle is associated with a Expanded Memory 
Manager. 

The following is an example of using the above technique: 


Examples 


EMM Device Name DB "EMMXXXXO" 


PUSH 

DS 



PUSH 

CS 



POP 

DS 



MOV 

AH, SDH 

Open File Function Call 

MOV 

DXjEMM Device Name 

Set ASCII Name 

in DX 

MOV 

AL, OH 

Open file in read only mode 

INT 

2IH 

Call Interrupt 

21H 

JC 

Open_Devi ce_Error 



MOV 

EMM_Handle,AX ; Save file handle 


MOV 

DX, Buffer 



MOV 

BX, EMM Handle 



MOV 

CX, OH 



MOV 

AX,44H 

IOCti function 

44H 

MOV 

AL,07H 

Subfunction 07 

Get Output Status 

INT 

2IH 

Call Interrupt 

21H 

MOV 

Status, AX 



MOV 

BX,EMM_Handle ; 
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MOV 

INT 


AH,3EH 

21H 


; Close File Handle 
; Call Interrupt 21H 


The second method of detecting the Expanded Memory Manager is by using 
the address that may be found in the 67H interrupt vector. The 67H interrupt 
is of course the one used by the EMM driver, this interrupt 67H vector 
contains the address iocation of the driver. By normai convention the 
memory iocation at an offset of OAH in the EMM drivers code segment 
contains the device driver name, EMMXXXXO (in our case), if the name is 
present at the iocation specified then the EMM driver is instalied. 

The foilowing is an exampie of using the above technique: 


Examples 


EMM_Devi ce_ 

name DB "EMMXXXXO" 

MOV 

AH,35H 

Get Interrupt vector 

MOV 

AL,67H 

EMM Interrupt number 

INT 

21H 

Call Interrupt 2IH 

MOV 

DI,0AH 

Segment is in ES, set the 



offset in DI 

LEA 

SI, EMM_Device_Name 

Offset of EMM name in SI 

MOV 

CX,08 

EMM String Name size in CX 

CLD 

REPE 

CMPSB 


Compare the names for a match 

JNE 

Error_Exi t 
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Appendix E. DOS Protected Mode Services 


The following section describes the DOS Protected Mede Services (DPMS) 
driver that is provided aleng with PC DOS 7. The driver is written by Novell** 
and is used by the Stacker** compression driver. 


Interrupt 

Function 

Description 

2FH 

AX=43E0H 

DPMS Installation Check 

31H 

AX=01 OOH 

Call Protected-Mode Procedure 

31H 

AX = 01 01 H 

Call Real-Mode Procedure (RETF) 

31H 

AX=01 02H 

Call Real-Mode Procedure (IRET) 

31H 

AX=01 03H 

Call Real-Mode Interrupt Flandler 

31H 

AX=0200H 

Allocate Descriptors 

31H 

AX = 0201 H 

Free a Descriptor 

31H 

AX=0202H 

Create Alias Descriptor 

31H 

AX=0203H 

Build Alias to Real-Mode Segment 

31H 

AX=0204H 

Set Descriptor Base 

31H 

AX=0205H 

Set Descriptor Limit 

31H 

AX=0206H 

Set Descriptor Type/Attribute 

31H 

AX=0207H 

Get Descriptor Base 

31H 

AX=0300H 

Get Size of Largest Free Block of Memory 

31H 

AX = 0301 H 

Allocate Block of Extended Memory 

31H 

AX=0302H 

Free Block of Extended Memory 

31H 

AX=0303H 

Map Linear Memory 

31H 

AX=0304H 

Unmap Linear Memory 

31H 

AX=0400H 

Relocate Segment to Extended Memory 


The DPMS driver makes its services available to DPMS clients via interrupts 
2FH and 31 H. In this section are briefly described the 2FH Multiplex Interrupt 
call that are provided if the DPMS driver is installed and the Interrupt 31 FI 
calls. 

For more detailed information please refer to the DOS Protected Mode 
Services specifications from Novell. 
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Interrupt 2FH Function AX=43E0H DPMS Installation Check 


Purpose 

This call is used to determine if the DPMS driver is installed and returns 
information about the driver. 

MOV AX,43E0H ; DPMS Installation Check 

INT 2FH ; Call DOS 2F Interrupt 

On Exit AX = OOOOh if installed 

ES:BX -> Registration Structure 


Format of registration structure: 


Offset 

Size 

Description 

OOh 


DWORD 

real -mode API entry point 

04h 


DWORD 

16-bit protected-mode API entry point 

08h 

8 

BYTEs 

reserved (0) 

lOh 

8 

BYTEs 

blank-padded server OEM name 

18h 


WORD 

flags 




bit 0: fast processor reset available (286 only) 




bits 1-15 reserved (undefined) 

lAh 

2 

BYTEs 

DPMS version (major, mi nor) 

ICh 


BYTE 

CPU type (02h = 286, 03h = 386 or higher) 


Interrupt 31 H Function AX=0100H Call Proteted-Mode Procedure 

AX = OlOOh cal 1 protected-mode procedure 
CX = number of words of stack to copy 
ES:DI -> callup/down register structure 


Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Callup/Down Register Structure” on page 323 for details of the 
callup/down structure. 

See “Interrupt 31 H DPMS Error Return Codes” on page 323 for possible 
errer return codes. 
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Interrupt 31H Function AX=0101H Call Real-Mode Procedure (RETF) 

AX = OlOlh call real -mode procedure (RETF return) 

CX = number of words of stack to copy 
ES:DI -> callup/down register structure 


Return 

CF clear if successful 
CF set on error 
AX = error code 


Comments 

See “Callup/Down Register Structure” on page 323 for details of the 
callup/down structure. 

See “Interrupt 31 H DPMS Error Return Codes” on page 323 for possible 
error return codes. 


Interrupt 31H Function AX=0102H Call Real-Mode Procedure (IRET) 

AX = 0102h call real -mode procedure (IRET return) 

CX = number of words of stack to copy 
ES:DI -> callup/down register structure 


Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Callup/Down Register Structure” on page 323 for details of the 
callup/down structure. 

See “Interrupt 31 H DPMS Error Return Codes” on page 323 for possible 
error return codes. 
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Interrupt 31H Function AX=0103H Call Real-Mode Interrupt Handler 


Purpose 

This function call transfers control to the address specified by the real-mode 
Interrupt vector. 

AX = 0103h call real -mode interrupt handler 
BL = interrupt number 
CX = number of words of stack to copy 
ES:DI -> callup/down register structure 

Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Callup/Down Register Structure” on page 323 for details of the 
callup/down structure. 

See “Interrupt 31 H DPMS Error Return Codes” on page 323 for possible 
error return codes. 


Interrupt 31 H Function AX=0200H Allocate Descriptors 
Purpose 

This function allocates one or more descriptors in the task's local descriptor 
table. The descriptors allocated must be Initialized by the application. 

AX = 0200h allocate descriptors 

CX = number of descriptors to allocate 

Return 

CF clear if successful 

AX = first descriptor allocated 
CF set on error 
AX = error code 
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Comments 


See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0201H Free a Descriptor 
Purpose 

Frees a previously allocated descriptor. 

AX = 0201h free a descriptor 
BX = descriptor 

Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” cn page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0202H Create Aiias Descriptor 
Purpose 

Creates a new descriptcr that has the same base and limit as the specified 
descriptor. 

AX = 0202h create alias descriptor 
BX = descriptor 

Return 

CF clear if successful 
AX = alias descriptor 
CF set on error 
AX = error code 
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Comments 


See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0203H Build Alias to Real-Mode Segment 
Purpose 

AX = 0203h build alias to real -mode segment 

BX = descriptor 

CX = real -mode segment 

Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0204H Set Descriptor Base 

AX = 0204h set descriptor base 
BX = descriptor 
CX:DX = base address 


Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 
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Interrupt 31 H Function AX=0205H Set Descriptor Limit 

AX = 0205h set descriptor limit 
BX = descriptor 
CX = 1 i mi t 


Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0206H Set Descriptor Type/ Attribute 

AX = 0206h set descriptor type/attribute 
BX = descriptor 
CL = type 
CH = attribute 


Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0207H Get Descriptor Base 

AX = 0207h get descriptor base 
BX = descriptor 


Return 

CF clear if successful 
CX:DX = base address 
CF set on error 
AX = error code 
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Comments 


See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0300H Get Size of Largest Free Biock of 
Memory 

AX = 0300h get size of largest free block of memory 

Return 

CF clear if successful 
BX:CX = size 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0301H Aiiocate Biock of Extended Memory 

AX = 0301h allocate block of extended memory 
BX:CX = size 


Return 

CF clear if successful 
BX:CX = base address 
SI:DI = handle 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0302H Free Biock of Extended Memory 

AX = 0302h free block of extended memory 
SI:DI = handle 


Return 

CF clear if successful 
CF set on error 
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AX = error code (see below) 


Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0303H Map Linear Memory 

AX = 0303h map 1 i near memory 
ES:[DI] = DOS 


Return 

CF clear if successful 
BX:CX = base address 
SI:DI = handle 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Interrupt 31H Function AX=0304H Unmap Linear Memory 

AX = 0304h unmap 1 i near memory 
SI:DI = handle 


Return 

CF clear if successful 
CF set on error 
AX = error code 

Comments 

See “Interrupt 31 H DPMS Errer Return Codes” en page 323 for possible 
errer return codes. 


Appendix E. DOS Protected Mode Services 321 



Interrupt 31 H Function AX=0400H Relocate Segment to Extended 
Memory 

AX = 0400h relocate segment to extended memory 

ES:SI = base address 

CX = 1 i mi t 

BL = type 

BH = attribute 

DX = selector or OOOOh 

Return: CF clear if successful 
AX = selector 
BX:CX = new base address 
SI:DI = handle 
CF set on error 
AX = error code 


Comments 

See “Interrupt 31 H DPMS Error Return Codes” on page 323 for possible 
error return codes. 
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Interrupt 31H DPMS Error Return Codes 


Table 2. 

DPMS Error Return Codes 

AX 

Description 

8000H 

General error 

8001 H 

Unsupported function 

801 1H 

Descriptor unavailable 

8012H 

Linear memory unavaiiabie 

8013H 

Physicai memory unavaiiabie 

8021 H 

Invaiid vaiue 

8022h 

Invaiid seiector 

8023H 

invaiid handle 


Callup/Down Register Structure 

The following is the format for the callup/down register structure that is used 
with interrupt 31H, function calls 0100H, 0101H, 0102H and 0103H. 


Offset 

Size 

Description 

OOH 


DWORD 

EDI 


04H 


DWORD 

ESI 


OSH 


DWORD 

EBP 


OCH 

4 

BYTEs 

Reserved 

(0) 

lOH 


DWORD 

EBX 


14H 


DWORD 

EDX 


18H 


DWORD 

ECX 


20H 


DWORD 

EAX 


24H 


DWORD 

EIP 


28H 


WORD 

CS 


2AH 

2 

BYTEs 

Reserved 

(0) 

2CH 


DWORD 

E FLAGS 


30H 


DWORD 

ESP 


34H 


WORD 

SS 


36H 

2 

BYTEs 

Reserved 

(0) 

38H 


WORD 

ES 


3AH 

2 

BYTEs 

Reserved 

(0) 

3CH 


WORD 

DS 


3EH 

2 

BYTEs 

Reserved 

(0) 

40H 


WORD 

FS 


42H 

2 

BYTEs 

Reserved 

(0) 

44H 


WORD 

GS 


46H 

2 

BYTEs 

Reserved 

(0) 
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Appendix F. Task-swapping 


The user-shell introduced with DOS 5.0 provides a task-swapper function. 
With it the user can switch from one application to another without 
terminating either application. When a user starts a new program, the 
task-swapper suspends the currently-active program (in this case, the 
session-manager program) saves the contents of all registers, and writes the 
contents of the program memory to disk or to where “SET TEMP=” is 
specified. A new session is then created by the loading and executing of the 
new program. (A session is a program that is executed directly by the 
task-swapper and runs independently of other sessions.) The task-swapper 
remains active, normally monitoring the keyboard for a predefined key 
sequence. When the user presses the key sequence, the task-swapper 
suspends and saves the current session and transfers control to the formerly 
suspended session. It reads the memory contents of another suspended 
session Into system memory, sets up the registers with the saved values, 
and transfers control to the formerly suspended session. 

Most application programs can be suspended without problems. Because 
they execute synchronously, they can be Interrupted In mid-execution and 
restarted (If the task-swapper properly saves and restores the state of the 
system that was in effect when it suspended the program). Some types of 
programs cannot operate safely with a task-swapper. Per example: 

• Some termlnate-stay-resident (TSR) programs. (These are 
memory-resident pregrams that are executed asynchrenously.) That Is, 
they execute and take contrel of the system Independently of the 
foreground program, the main program In control of the system. A 
network utility which performs tasks "in the background" while the 
foreground application is inactive is an example of this type of program. 

If a program with an outstanding network read request is suspended and 
replaced with anether program, the network utility can copy the 
requested data Into the secend program's context. This data can 
overwrite code or data used by the second program, causing a system 
malfunctlen. 

• Seme types of mainframe communications software. Mainframe 
communication software is normally communicating with software on 
another system. 

• Software that maintains separate data for each process running on the 
system (a process is any program running within a session). One 
example of this type of software is a network redirector which traps DOS 
function calls to provide access to a simulated drive, but which does not 
use Internal data structures maintained by DOS. While a task-swapper 
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" Windows is 


might adjust these data structures during a session switch, a redirector 
which does not reiy on these tabies must be abie to maintain this 
information by itself. Consequently, the redirector must be notified of a 
session switch and must be able to prevent or delay the switch until it 
can handle the switch properly. 

The DOS task-swapping protocol gives this type of software the ability to 
coexist with task-swappers that conform to the protocol. The protocol 
specifies a standard method of communication between the task-swapper 
and other software on the system, and gives software that would be 
adversely affected by a session switch the opportunity to control the timing of 
a switch or to prevent it altogether. Finally, the protocol provides a standard 
method for task-swappers to cooperate with each other, minimizing the 
problems that would result when competing task-swappers exist on the 
system simultaneously. Programs which conform to the DOS Task-swapping 
Protocol can coexist safely with the task-swappers incorporated in DOS 5.0 
and later, and in future versions of Windows" running in real and standard 
modes. 

Windows running in 386 enhanced mode is a preemptive, multitasking 
system. For this reason, it has a different set of requirements than swappers 
that do not support multitasking. 

To be "safe" in both task-swapping and multitasking environments, clients 
and task-swappers must support both types of environments. This appendix 
describes the requirements for safe operation in a task-swapping 
environment. Flowever, programs that are to run safely in a multitasking 
environment must also use the Windows 386 enhanced mode Int 2FH 
interface and are likely to require a specialized Windows 386 enhanced mode 
virtual device. These programs may need also to maintain separate instance 
data for task-swapper sessions and for virtual devices. 

For more information on the Windows 386 enhanced mode virtual devices 
and the Int 2FH interface, see the Microsoft Windows Device Driver Kit Virtual 
Device Adaptation Guide. 

The DOS task-swapping protocol specifies a standard method for 
task-swappers and other programs so they can cooperate with each other. 
Task-swappers and other types of programs exist in a client/server 
relationship in which the task-swapper is the server and other programs act 
as clients. This chapter uses the term client to refer to a program that 
conforms to this protocol and is not a task-swapper. As noted above, most 
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task-swappers work by suspending one session, moving that session to a 
disk or to extended or expanded memory, and then ioading another 
appiication in the same address space. However, in most systems there are 
other areas of memory, such as memory occupied by DOS, device drivers, 
and TSR utiiities that are not swapped. In neariy every case, the programs 
that occupy this memory were started before the task-swapper, and are 
running and accessibie regardiess of which appiication the task-swapper has 
ioaded into system memory. These type programs are referred to as giobai 
software. Memory that remains unchanged through task switches is caiied 
giobai memory. Locai memory, on the other hand, is memory associated 
with a session spawned by the task-swapper. When the task-swapper swaps 
the session, this memory is swapped to disk or to extended or expanded 
memory. 

Client Initialization 

One of the first responsibilities of the task-swapper is to add itself to the 
chain of Int 2FH handlers by calling the Get Interrupt Vector Int 21 H function 
(AH = 35H) and the Set Interrupt Vector Int 21 H function (AH = 25H). After a 
client program has installed itself in the interrupt chain, it must determine 
whether a task-swapper is already present by calling the Detect swapper Int 
2FH call-in function. If a task-swapper is present, the function returns with 
the call-in address of the task-swapper in ES:DI. Using the call-in address in 
ES:DI, the client must call the Hook Call-Out call-in function to allow the 
task-swapper to add the client's call-out function handler address to the 
chain of call-out handlers it is maintaining for the session in which the client 
is running. 

The Client Int 2FH Handler 

The task-swapper issues an Int 2FH to call two client functions, the Build 
Call-Out Chain function and the Identify Instance Data function. Both of these 
functions are called by the task-swapper to build a linked list of data 
structures. Depending on the function, each structure identifies a particular 
client's call-out function handler address or a client's instance data. In 
general, the client Int 2FH handler performs the following tasks to add its 
structure to the list: 

1. The Int 2FH handler determines whether AX contains a value identifying a 
task-swapper call-out function. If not, it transfers control to the previous 
Int 2FH handler with a far jump. 

2. If AX identifies a task-swapper call-out function, the Int 2FH handler 
pushes the flags and makes a far call to the previous Int 2FH handler. 
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3. When the call returns, the Int 2FH handler places the value In ES:BX (the 
address of the previous handler's data structure) in the appropriate field 
of the client's data structure. 

4. The Int 2FH handler places the address of the client's own data structure 
In ES:BX and returns from the Interrupt. The specific actions taken by the 
Int 2FFI handler and the data structure used depends on the particular Int 
2FH call-out function. 

Responding to a Pending Session Switch 

Most clients must be able to prevent a session switch from occurring when 
the client or other software is in an unstable state during which a session 
switch could result in the loss or corruption of data. 

A task-swapper calls two call-out functions before performing a session 
switch. The Query Suspend function provides notification to affected clients 
that the task-swapper is preparing to suspend the currently active session. 
When a client receives a call to this function, It can either perform whatever 
operations are required and then allow the session switch to proceed, or It 
can prevent the session switch altogether. 

The task-swapper calls the Suspend Session call-out function of each client if 
no client fails the Query Suspend call. Since interrupts were enabled while 
the task-swapper was making the Query Suspend call, the system state could 
have changed after a given client had received the call. The Suspend 
Session call provides clients one last opportunity to prevent the session 
switch. Since the task-swapper calls this function with Interrupts disabled, 
the system state Is guaranteed not to change following the Suspend Session 
call until the session switch takes place. For this reason Interrupts must 
remain disabled until all clients have returned from the call. Also, a client 
must not issue software interrupts or use calls that might enable Interrupts. 
The client can only return zero In AX to permit the session switch or one to 
prevent the session switch. All other registers must be preserved. 

A client must not fail a Query Suspend or Suspend Session call because an 
asynchronous API Is being executed without first determining that the 
applications program Interface (API) Is not being handled by more competent 
software. The client determines this by calling the Query API Support call-in 
function. 

If any client fails the Query Suspend or Suspend Session calls, all clients in 
the entry-point chain called by the task-swapper may receive a Session 
Active call for the session that was to be suspended. For this reason it is 
possible to receive a Session Active call for a session that has not been 
suspended or activated. Clients can safely Ignore these calls. 
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If no client fails the Suspend Session call, the task-swapper replaces the 
current interrupt vector table with a saved copy before enabling interrupts. 
The saved copy represents the global state present when the task-swapper 
was first started. This guarantees that interrupt handlers local to the session 
being suspended are not called until the sessicn is resumed. 

Between the Suspend Session call and the next Activate Session call 
interrupts are enabled intermittently and global software can receive 
interrupts during this time. GIcbal clients must net assume the contents of 
any nonglobal memory between Suspend Session and Activate Session calls. 

The task-swapper calls the Activate Session call-out function of affected 
clients te netify them that a task is about to be resumed. It then calls the 
Sessicn Active function when the previously suspended session has been 
loaded into memory (including its local memory and interrupt vector table) 
and interrupts have been enabled. 

Responding to the Pending Creation of a New Session 

Just as a client can prevent a sessien switch, a client also can prevent the 
task-swapper from creating a new session. Before creating the new session, 
the task-swapper calls the Create Session call-out function. A client can take 
the appropriate acticn to prepare fcr the new session (for example, allocating 
additional memory to hold information for the session) and then permit the 
task-swapper to create the new session. Or the client can fail the Create 
Sessicn call tc block the new session from being created. A client would 
prevent a new session from being created, for example, if it maintained 
session-data in a fixed-length buffer that was too full to accommodate 
ancther session. 

If any client fails the Create Session call, the task-swapper calls the Destrcy 
Session function of some or all clients. The Destrcy Session function notifies 
client programs that the sessicn ID passed with the Create Session call is no 
longer valid. Since the task-swapper may call all clients er only those clients 
that had received the Create Session call, it is possible tc receive a Destroy 
Session call for a session that has not been created or activated. Clients can 
safely igncre this Destroy Session call. 

If no client fails the Create Session call, the task-swapper usually suspends 
the current sessien and then calls the Activate Session function by using a 
flag set to notify clients that the new session is about to take control. This 
gives clients the opportunity to take whatever acticn is required to prepare 
fcr the new session. The task-swapper then calls the Sessicn Active (again 
with a flag set) to notify clients that the new session has been started. 
Hcwever, because some session managers (such as Windows) permit the 


Appendix F. Task-swapping 329 



user to start a session in an inactive state, the Activate Session and Session 
Active calls might not occur Immediately after the Create Session call. Other 
sessions might also be activated and suspended before the newly created 
session becomes active for the first time, If at all. 


Client Termination 

Before terminating, a client must perform two tasks: 

• It must call the Unhook Call-Out call-in function. This removes its call-out 
function handler from the chain of local call-out handlers maintained by 
the task-swapper. 

• The client must remove Its Int 2FH handler from the chain of Int 2FH 
handlers by calling the Set Interrupt Vector Int 21 FI function (AH = 25H), 
replacing the Int 2FH Interrupt vector with the address of the previous Int 
2FH handler (saved when the client was initialized). 


The Switch_Caii_Back_info Data Structure 

Every client must maintain a Switch_Call_Back_lnfo (SCBI) data structure. 
The client supplies this structure to the task-swapper when calling or 
responding to several different functions. The SCBI structure contains 
information about the entry point of the client's call-out function handler and 
a pointer to a list of API_lnfo_Struc data structures. These structures specify 
the types of asynchronous API which the client supports and the level of 
support It Is able to provide. The Swltch_Call_Back_lnfo data structure Is 
defined as follows: 


Switch Call Back Info 

STRUC 

SCBI_Next 

dd ? 

SCBI_Entry_Pt 

dd ? 

SCBI Reserved 

dd ? 

SCBI API Ptr 

dd ? 


; address of next structure in chain 
; address of notification function handler 


Switch Call Back Info ENDS 


The Swltch_Call_Back_lnfo structure contains the following fields: 

• SCBI_Next - This 32-blt value contains a pointer to the next structure in 
the client chain. A task-swapper calls the Build Call-Out Chain Int 2FH 
call-out function to build this chain. 

• SCBI_Entry_Pt - This 32-blt value contains a pointer to the entry point of 
the client's call-out function handler. 

• SCBI_Reserved - This 32-bit value Is reserved for use by the 
task-swapper. 


330 PC DOS 7 



• SCBI_API_Ptr - This 32-bit vaiue contains a segment:offset pointer to a 
zero-terminated iist of API_lnfo_Struc data structures. These structures 
specify the type ef support the ciient prevides for various asynchronous 
APIs. 

The APMnfo_Struc Data Structure 

The API_infe_Struc (AIS) data structure contains information about the ievel 
of support that a ciient provides to a particular type of asynchronous API. 
The API_lnfo_Struc structure is defined as foiiows: 

API_Info_Struc STRUC 


AIS_Length dw 10 
AIS_API dw ? 
AIS_Major_Ver dw ? 
AIS Minor Ver dw ? 


AIS_Support_Level dw ? 
API Info Struc ENDS 


The APi_lnfo_Struc data structure contains the foiiewing fieids: 

1. AiS_Length - This 16-bit value specifies the iength of the AIS data 
structure. 

2. AIS_API - This 16-bit vaiue specifies the ID of the asynchronous API 
supported by the client. The following values are defined: 


APIJETBIOS 

equ 1 

; NETBIOS 

API_8022 

equ 2 

; 802.2 

API_TCPIP 

equ 3 

; TCP/IP 

API_LANMAN 

equ 4 

; LAN Manager named pipes 

APIJPX 

equ 5 

; NetWare IPX 


• AIS_Major_Ver - This 16-bit value specifies the highest major version of 
the API for which the client provides the level of support specified by the 
AIS_Support_Level field. For example, if the highest version of the API 
supperted by the client at the specified level is 3.10, this field would be 
set to 3h. 

• AIS_Minor_Ver - This 16-bit value specifies the highest minor version of 
the API for which the client provides the specified level of support. For 
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example, if the highest version of the API supported by the client at the 
specified level is 3.10, this field would be set to Ah. 

• AIS_Support_Level - This 16-blt value specifies the level of support 
provided by the client for the particular version of the API. The range 
and significance of values In this field depends upon the particular API. 
The following definitions are used for NETBIOS: 

- Minimal support. The client prevents a session switch after the 
application has executed any asynchronous API, even after the 
request has been completed. 

- API-level support. The client tracks asynchronous requests that are 
outstanding and prevents task switches at those times. The client 
allows task switches after all outstanding asynchronous requests 
have completed. 

- swapper compatibility. The API provider allows switches to occur 
even when asynchronous requests are outstanding. However, this 
might be limited by such factors as buffer size, and some requests 
might fail. 

- Seamless compatibility. The API provider always allows session 
switches to occur, and this never causes loss of data. 

The Win386_Startup_lnfo_Struc Data Structure 

The Wln386_Startup_lnfo_Struc data structure Is defined as follows: 


Wi n386_Startup_Info_Struc 

STRUC 



SIS_Version 

db 

3,0 

i gnored 

SIS_Next_Dev_Ptr 

dd 

7 

Ptr to previous handler's 
Wi n386_Startup_Info_Struc 

SIS_Vi rt_Dev_Fi 1 e_Ptr 

dd 

0 

i gnored 

SIS_Reference_Data 

dd 

7 

i gnored 

SIS_Instance_Data_Ptr 

dd 

7 

Ptr to IIS structures 


Win386_Startup_Info_Struc ENDS 

The Win386_Startup_lnfo_Struc Is the same structure used to respond to the 
Microsoft Windows startup Int 2FH function. However, the DOS task-swapper 
uses only the SIS_Next_Dev_Flle_Ptr and SIS_lnstance_Data_Ptr fields. (For 
Information on the other fields, see the Microsoft Windows Device Driver Kit 
Virtual Device Adaptation Guide.) 

The Win386_Startup_lnfo_Struc data structure contains the following fields: 

• SIS_Verslon - This two-byte field Is not used. 
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• SIS_Next_Dev_Ptr - This 32-bit vaiue contains a segment:offset pointer 
to the next structure in the ciient chain. See beiow fer mere information 
about how this chain is constructed. 

• SIS_Virt_Dev_Fiie_Ptr - This 32-bit fieid is not used. 

• SIS_Reference_Data - This 32-bit fieid is net used. 

• SIS_lnstance_Data_Ptr - This 32-bit vaiue contains a segment:offset 
pointer to a list of lnstance_ltem_Struc data structures. Each structure 
describes ene contigueus block of instance data. The list is terminated 
by a 32-bit zero value. 


The lnstance_ltem_Struc Data Structure 

The Instance Item Struc data structure is defined as follows: 


Instance_Iteni_Struc STRUC 

IIS_Ptr dd ? 

IIS_Size dw ? 

Instance_Iteni_Struc ENDS 

The lnstance_ltem_Struc structure contains the following fields: 

• IIS_Ptr - This 32-bit value contains a segment:offset pointer to the first 
byte of the block of instance data. IIS_Size - This 16-bit value specifies 
the size, in bytes, of the block of instance data. 

The Swapper_Ver_Structure 

The following shows the definition of the Swapper_Ver_Struc data structure: 


Swapper_Ver_Struc STRUC 


SVS_API_Major 

SVS_API_Minor 

SVS_Product_Major 

SVS_Product_Mi nor 

SVS_swapper_ID 

SVS_Flags 

SVS_Name_Ptr 

SVS_Prev_Swapper 


dw ? 
dw ? 
dw ? 
dw ? 
dw ? 
dw ? 
dd ? 
dd ? 


Swapper_Ver_Struc ENDS 


The Swapper_Ver_Struc contains the following fields: 
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• SVS_API_Major - This 16-bit vaiue specifies the highest major version of 
the Task-swapping Protocoi that the swapper supports. For exampie, if 
the highest version of the protocoi supported by the ciient at the 
specified ievei is 3.10, this fieid wouid be set to AH. The current version 
is 1.0. 

• SVS_API_Minor - This 16-bit vaiue specifies the highest minor version 
of the Task-swapping Protocoi that the swapper supports. For exampie, if 
the highest version of the protocoi supported by the task-swapper is 3.10, 
this fieid wouid be set to AH. The current version is 1.0. 

• SVS_Product_Ma]or - This 16-bit vaiue specifies the major version of the 
task-swapper, in the same format as SVS_APi_Major. 

• SVS_Product_Minor - This 16-bit vaiue specifies the minor version of the 
task-swapper, in the same format as SVS_APi_Minor. 

• SVS_Swapper_ID - This 16-bit fieid specifies, in its iow-order four bits, 
the swapper iD vaiue obtained from the Aiiocate swapper ID function. 

• SVS_Fiags - This 16-bit fieid contains a bit-array of 16 bits used as flags. 
In this version of the Task-swapping Protocoi, oniy bit 0 is used. If the 
swapper is currentiy disabied, bit 0 is set. Otherwise, bit 0 is ciear. 

• SVS_Name_Ptr - This 32-bit vaiue contains a segment:offset pointer to a 
zero-terminated ASCIi string that identifies the task-swapper (for 
exampie, "DOS Sheil Task-swapper"). 

• SVS_Prev_Swapper - This 32-bit vaiue contains the address (in 
segment:offset form) of the previousiy ioaded swapper's caii-out function 
entry point that is returned by the Detect swapper int 2FH task-swapper 
function. 


Function Descriptions 

This section describes the Int 2FH handler functions, task-swapper caii-out 
functions, and task-swapper cail-in functions that comprise the DOS 
Task-swapping Protocoi. The function descriptions are grouped according to 
these categories. Within each category the function descriptions are 
described in numeric order. Each function description is headed by the 
name of the function foilowed by a brief description of the function and the 
required conditions at the entry and exit of the function. Optionai comments 
appear foilowing the entry and exit information. 

Note: AM registers not used by these functions must be preserved. 
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Task-swapper Int 2FH Handler Functions 

Currently there is one Int 2FH function for the task-swapper. It is specified 
below: 

Detect Swapper (Function 4B02H) 

A client calls the Detect Swapper Int 2FH function to determine if a 
task-swapper is currently running and to obtain the address of its call-in (to 
the task-swapper) function entry point. 


Example: 


MOV 

AX,04B02H 

; Detect presence of a task-swapper 

XOR 

BX,BX 

;Required for future extensibility 

XOR 

DI,DI 


MOV 

ES,DI 


INT 

2FH 



Save call-out address to the current task-swapper 


MOV WORD PTR 0UT_T0_SWAPPER+0, DI 
MOV WORD PTR 0UT_T0_SWAPPER+2, ES 


0UT_T0_SWAPPER DO 0 ; Cal 1 -out address to the current 

task-swapper 

All other registers are preserved. 

Comments 

A non-NULL pointer returned in ES:DI indicates the presence of a 
task-swapper. AX is returned with zero for future extensibility and the carry 
flag is clear. 

Clients call this function during initialization and take the appropriate action if 
a swapper is detected. 

Client Int 2FH Handler Functions 

A client that is in full compliance with this protocol must contain an Int 2FH 
handler that can properly respond to the Build Call-Out Chain function 
(4B01H) from the task-swapper. In addition, it must also respond to the 
Identify Instance Data function (4B05H) if the client maintains data for each 
session. The following sections describe these functions. 
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Build Call-out Chain 

This Client Int 2FH Handler function links a client's call-out function entry 
point to a chain of client call-out entry points on the swapper. 

On Entry: 

; Respond to Call_0ut function from task-swapper 


cmp 

ax,04b01h 

; Bui Id Chain Call-in function? 

jnz 

Pass Function On 


test 

Bit_f lag, 00000001b 


jnz 

Pass_Function_0n 



;ES:BX = 0:0 for future extensibility 

;CX:DX = call-in address of the calling task-swapper 

9 

pushf 

call far Prev_Int2f_Handler 

;ES:BX = 0:0 if the first client loaded in memory 


9 

mov offset SCBI_Next,bx 

mov offset SCBI_Next+2,es 

Back_to_swapper: 

or Bit_flag,l ;We've been here 

mov bx, offset Swap_Cal l_Back_Info 

mov es,cs 

;A11 other registers must be preserved, 
i ret 


Pass_Function_On: 

9 

jmp far Prev_Int2f_Handler 


Bit_flag db 0 ; bit 1 = 0 if not called by swapper 

; = 1 if called by the swapper 

Comments 

ES:BX = 0:0 if you are first client loaded in-memory 
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A task-swapper calls this function to create a linked list of the call-out 
function entry points of all global clients, clients running in the current 
session, and of information about the asynchronous APIs supported by each 
client. When the functien returns, ES:BX contains a pointer te the client's 
SCBI data structure centaining this information. 

Swap_Cal l_Bacl<_Info STRUC 


SCBI 

Next 

dd 

7 

; pointer to next structure in list 

SCBI 

_Entry_Pt 

dd 

7 

;CS:IP of entry point procedure 

SCBI 

Reserved 

dd 

7 

;used by the swapper 

SCBI 

[API_Ptr 

dd 

7 

; pointer to list of API structures 


Swap_Cal l_Bacl<_Info ENDS 

For a description of the SCBI data structure, see “The Swltch_Call_Back_lnfe 
Data Structure” on page 330 in this manual for a description of this structure. 

When a client receives an Int 2FH, it checks AX to determine whether the Int 
2FH is calling a Client Int 2FH Handler function. If not, the client passes 
control to the previous Int 2FH handler using a far jump. If It Is, the Client Int 
2FH Handler routine Immediately pushes the flags and call the previous Int 
2FH vector using a far call. It does not modify any registers befere making 
the call. 

When the call returns, ES:BX will centain the address ef the previous client's 
SCBI data structure (or 0:0 If the current client was the first leaded into 
memory). Whether or not ES:BX is 0:0, the value In ES:BX is placed in the 
SCBI_Next field of the client's SCBI data structure. The client then places the 
address of Its SCBI data structure Inte ES:BX and then returns frem the 
Interrupt. 

When the call returns te the calling task-swapper, ES:BX peints to the SCBI 
data structure of the last client loaded Into memory. As a result, the SCBI 
data structures of the most recently loaded clients appear near the head ef 
the chain. Consequently, the most recently loaded clients will be called 
before clients that were loaded earlier. This weuld allow, for example, an 
application with outstanding asynchronous requests to cancel the request 
when a session swap Is about to occur before the network Is queried. If the 
calls were to occur in the reverse order, the netwerk might block the sesslen 
swap because of the outstanding asynchronous requests. 

At the entry te the Build Call-In Chain function, CX:DX contains the call-in 
function entry point of the calling task-swapper. A client can call this reutine, 
with arguments specifying the function to be performed, while it is handling 
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the Int 2FH call. However, the address passed In the Int 2FH call may not be 
the same address made available In later call-out function calls. 

Identify Instance Data 

This Client Int 2FH Handler function identifies instance data maintained by 
the client. For example: 

On Entry: 

; Respond to Call_0ut function from task-swapper for Instance Data 

cmp ax,04b05h ;Build Chain Call-in function? 

jnz Pass_Function_On 

9 

;ES:BX = 0:0 for future extensibility 

;CX:DX = call-in address of the calling task-swapper 

;Calls to DOS can be made 

;Make call to previous client's Win386_Startup_Info_Struc 
; data structure 

9 

pushf 

call far Prev_Int2f_Handler 

mov offset SIS_Next_Dev_Ptr,BX 

mov offset SIS_Next_Dev_Ptr+2,ES 

Back_to_swapper: 

9 

; Provide Win386_Startup_Info_Struc data structure address 

9 

mov bx, offset Win386_Startup_Info_Struc 

push cs 

pop 

iret ;A11 other registers must be preserved 

Pass_Function_On: 

jmp far Prev_Int2f_Handler ;to previous Int 2FH handler 


Wi n386_Startup_Info_Struc 

STRUC 


SIS_Version 

db 

3,0 

i gnored 

SIS_Next_Dev_Ptr 

dd 

7 

Ptr to previous handler's 

Wi n386_Startup_Info_Struc 

SIS_Vi rt_Dev_Fi 1 e_Ptr 

dd 

0 

i gnored 
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SIS_Reference_Data dd ? ; ignored 

SIS_Instance_Data_Ptr dd ? ; Ptr to IIS structures 

Win386_Startup_Info_Struc ENDS 

Comments 

A task-swapper calls this function to create a linked list of instance data 
blocks of all clients running on the system. 

When a client receives an Int 2FH, it checks AX to determine whether the Int 
2FH is calling a Client Int 2FH Flandler function. If It is not, the client passes 
contrel to the previous Int 2FFI handler by using a far jump. If It is, the client 
Int 2FFI handler routine Immediately pushes the flags and call the previous 
Int 2FFI vector using a far call. It does not modify any registers before making 
the call. 

When the call returns, ES:BX will centain the address ef the previous client's 
Win386_Startup_lnfo_Struc data structure (or 0:0 if the current client was the 
first loaded Inte memory). Whether or not ES:BX Is 0:0, the value in ES:BX is 
placed In the SIS_Next_Dev_Ptr field ef the client's Win386_Startup_lnfo_Struc 
data structure. The client then places the address ef its 
Win386_Startup_lnfe_Struc data structure into ES:BX and returns from the 
interrupt. 

When the call returns te the calling task-swapper, ES:BX points to the 
Win386_Startup_lnfo_Struc data structure of the last client leaded Into 
memory. 

Task-swapper Call-In Functions 

The DOS task-swapper Is In full compliance with this pretecel and contains a 
call-in function entry point that can properly respond to the follewing seven 
functions: 

• Get Version (Function OH) 

• Test Memory Region (Function 1H) 

• Hook Call-out (Function 4H) 

• Unhook Call-out (Function 5H) 

• Query API Support (Function 6H) 

The fellowing sections describe these functions. 
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Note: All task-swapper call-in functions return with the carry flag clear. If a 
call-in function returns with the carry flag set, the function is not 
implemented by the receiving task-swapper. 


Get Version 

This task-swapper call-in function identifies the current task-swapper, its 
version number, and the level of the task-swapping Protocol that it supports. 


For Example: 


MOV 

CLI 

CALL 


AX,0 ;Get Version call to the task-swapper 

; Interrupts disabled 

0UT_T0_SWAPPER ;From Detect swapper Int 2FH, AX=4b02h 


;AX = 0 for future extensibility 
;A11 other registers are preserved. 

;Save address of the swapper's Version 
; Data structure 

MOV SWAPPER_VER_STRUC_PTR+0,BX 

MOV SWAPPER_VER_STRUC_PTR+2,ES 


SWAPPER_VER_STRUC_PTR DO 0 


Comments 

The following shows the definition of the Swapper_Ver_Struc data structure. 
Swapper_Ver_Struc STRUC 


SVS_API_Major dw ? 
SVS_API_Minor dw ? 
SVS_Product_Major dw ? 
SVS_Product_Mi nor dw ? 
SVS_Swapper_ID dw ? 
SVS_Flags dw ? 
SVS_Name_Ptr dd ? 
SVS_Prev_Swapper dd ? 


Swapper_Ver_Struc ENDS 

For a description of the Swapper_Ver_Struc data structure, see “The 
Swapper_Ver_Structure” on page 333 in this manual. 
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Test Memory Region 


This task-swapper call-in function is used to identify global or local memory 
locations to the current session. Memory that is global is not replaced when 


a task-swap occurs. 

For Example: 

MOV AX,1 

MOV DI, OFFSET BUFFER 

MOV ES,SEG_BUFFER 

MOV CX,BUFFER_LENGTH 

CLI 

CALL 0UT_T0_SWAPPER 

MOV REGI0N_L0CATI0N,AX 


Test memory region call-out to the 
task-swapper 

Address of buffer to be tested 
ES is the buffer's segment address 
Length of buffer in bytes (0 to 65535) 
where 0 indicates 64K bytes (65536) 
Interrupts disabled 
Obtained from Detect Swapper 
Int 2FH, AX=4b02h 

Carry flag is clear 

AX = 0, Buffer is in global memory 
AX = 1, Buffer is partially in global 
and partially in local memory 
AX = 2, Buffer is in local memory 


All other bits are reserved and must be 0 
All other registers are preserved. 


Comments 

If the buffer to be tested is longer than 64K bytes, more than one call is 
required to test the entire region. The determination whether memory is 
global or local is performed by the current task-swapper. Clients check the 
status of memory following each Query Suspend or Session Active call to 
determine whether the memory is global or local to the task-swapper 
performing the session swap. 

Global software can use this function to identify asynchronous calls coming 
from another layer of global software. In these cases, the global software 
would not have to take special action when a session swap occurs because 
the calling application's buffer and callback address would be accessible 
regardless of which session is currently running. 

A memory-resident utility also could use this function to determine whether it 
is running locally within a session. For example, a communication 
application could temporarily shut down before being suspended. If the 
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application were running globally, however, that action that would not be 
necessary because the application would not be affected by a session swap. 

Hook Call-out 

This call-in function adds the address of the calling client's call-out function 
handler to the task-swapper's call-out chain. 

For Example: 


MOV 

AX, 4 

;Call-out to swapper to add this client's 
; Call-out address 

MOV 

DI, OFFSET SWAP_CALL_ 

_BACK_ 

_INF0 

MOV 

ES,CS 


Swap_Cal l_Back_Info (SCBI) 
data structure 

Interrupts are enabled. 

Calls to DOS can be made. 

CALL 

0UT_T0_SWAPPER 

; Obtained from Detect swapper 


; Int 2FH, AX=4b02h 

9 

;Carry flag is clear. 

9 

;AX = 0 for future extensibility 

9 

;A11 other registers are preserved 

Note: The client is not expected to fill in the SCBI_Next field for this 
structure. See “The Switch_Call_Back_lnfo Data Structure” on 
page 330 in this manual for more information. 

Comments 

During initialization a client calls the Detect swapper task-swapper Int 2FH 
function. If this call indicates that a task-swapper is running, the client calls 
the Hook Call-out call-in function of the task-swapper to add its own call-out 
handler to the task-swapper's call-out chain. Although some task-swappers 
create a call-out chain before every task-swapper event by calling the Build 
Call-out Chain Int 2FH function, other task-swappers generate this list only 
when initializing. These task-swappers keep a separate chain for each 
session. Each time the task-swapper creates a new session, it gives the 
session a copy of the global chain that was generated when the 
task-swapper initialized. (Alternatively, the task-swapper can keep a single 
global chain and a separate local chain for each session.) After the session 
is created, a client that runs locally within that session must explicitly add its 
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call-out handler address to the local chain by calling the Hook Call-out call-in 
function. 

A client must explicitly unhook itself from the call-out chain before 
terminating. The Unhook Call-out task-swapper call-in function unhooks a 
client from the task-swapper's call-out chain. 


Unhook Call-out 

This call-in function removes the address of the calling client's call-out 
function handler from the task-swapper's call-out chain. 

For Example: 


MOV 


MOV 

MOV 


AX, 5 


Call-in to swapper to remove 
this client's call-out address 


DI, OFFSET SWAP_CALL_BACK_INFO 


ES,CS 


CALL OUT TO SWAPPER 


Swap_Cal l_Back_Info (SCBI) 
data structure 
Interrupts are enabled. 

Calls to DOS can be made. 

Obtained from Detect swapper 
Int 2FH, AX=4b02h 

Carry flag is clear. 

AX = 0 for future extensibility 

All other registers are preserved 


See “The Switch_Call_Back_lnfo Data Structure” on page 330 in this manual 
for more information. 

Comments 

During initialization, a client calls the Detect swapper task-swapper Int 2FH 
function. If this call indicates that a task-swapper is running, the client calls 
the Hook Call-out call-in function of the task-swapper to add its own call-out 
handler to the task-swapper's call-eut chain. Then, before terminating, a 
client must explicitly call the Unhook Call-out function to remove itself from 
the call-out chain. 
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Query API Support 

This call-out function tells a client If it sheuld control session swapping to 
handle a particular asynchronous API. 

For Example: 


MOV AX, 6 

MOV BX,ID 


CALL 0UT_T0_SWAPPER 


Call-out to swapper for most capable 
API handler 


ID value of the asynchronous 

API 

API NETBIOS 

equ 1 


API 8022 

equ 2 


API TCPIP 

equ 3 


API LANMAN 

equ 4 


APIJPX 

equ 5 


Obtained from 

Detect swapper 

Int 


AX=4b02h 


MOV BEST_API_SUPP0RTER+0,BX 

MOV BEST_API_SUPP0RTER+2,ES 


Carry flag is clear. 

AX = 0 for future extensibility 
All other registers are preserved 


API_Info_Struc STRUC 


AIS Length 

dw 

7 

; length of the structure 

AIS_API 

dw 

7 

;the API ID val ue 

AIS_Major_Ver 

dw 

7 

;major version of API spec 

AIS_Mi nor_Ver 

dw 

7 

;minor version of the API spec 

AIS_Support_Level 

dw 

7 

;support level 


API_Info_Struc ENDS 

Note: See “The API_Info_Struc Data Structure” on page 331 in this manual 
for more information and the description of the AIS_API field. 


Comments 

This function determines which client will control session swapping (with 
regard to a particular asynchronous API). When a client is processing a 
Query Suspend or a Suspend Session call-out function, but before it prevents 
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the session swap because of the state of an asynchronous API, it must first 
call the Query API Support call-in function to determine if it is the most 
competent client to handle the API. If It Is, it prevents the session swap. If It 
Is not the most competent client It does not prevent the session swap, relying 
instead on the more competent client to prevent the session swap, if 
necessary. 

Every asynchronous API is assigned an ID value. Several levels of support 
are defined and indicated by a numeric value. Clients that can allow session 
swapping under more circumstances have a higher level of support than 
other clients. 

Client programs maintain information about the asynchronous APIs they 
support and the level of support provided to each. It is in a list of 
API_lnfo_Struc data structures. A client provides a pointer to the beginning 
of this list in its Swap_Call_Back_lnfo (SCBI) data structure. See “The 
API_lnfo_Struc Data Structure” on page 331 in this manual for a full 
description of the API_lnfo_Struc structure. See “The Swltch_Call_Back_lnfo 
Data Structure” on page 330 in this manual for more Information on the SCBI 
data structure. 

This function identifies the client most competent to support a specific API by 
returning the address of the API_lnfo_Struc data structure of the most 
competent client. The most competent client is the client that supports the 
highest version of the API. If two or more clients support the same highest 
version, the most competent client Is the one that provides the highest level 
of support for that version. 

If the calling client determines that the API_lnfo_Struc address returned by 
this function is the same as its own API_lnfo_Struc, the client prevents the 
session swap. 

Task-swapper Call-in Functions 

A client that is in compliance with this protocol contains a call-out function 
entry point that can properly respond to any of eight functions: 

• Init swapper (Function 0) 

• Query Suspend (Function 1) 

• Suspend Session (Function 2) 

• Activate Session (Function 3) 

• Session Active (Function 4) 

• Create Session (Function 5) 
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• Destroy Session (Function 6) 

• Swapper Exit (Function 7) 

A ciient is not required to impiement any particuiar function and can respond 
to any of these function calis by returning controi to the caliing task-swapper. 
The foiiowing sections describe these functions. 


Init swapper 

This task-swapper cali-out function notifies client programs that a new 
task-swapper is being initiaiized. 

For Example: 


CMP AX,0 


Ini t swapper cal 1 ? 

ES:DI = the call-out address to the 
calling task-swapper. 

Interrupts are enabled. 

Calls to DOS can be made. 


;The task-swapper can safely load, nonzero value 
; indicates that the task-swapper should not load. 

MOV AX,0KAY_T0_SWAP 

RET ; Return to task-swapper 


0KAY_T0_SWAP DB 0 ;Flag to indicate if its okay to swap away 


Comments 

Because it is not necessarily the task-swapper that calis this function, ciients 
should not assume that the call-out address passed in ES:Di wiii be the same 
address passed with subsequent caii-in functions. This address can be 
NULL. 

A session-manager appiication or environment that supports session 
swapping must caii this function when it is initiaiized. A giobal ciient that 
needs to take speciai action to coexist with a task-swapper does so when it 
receives this cali. The cail-in entry point provided in ES:Di must be abie to 
respond to the Get Version cali-in function. 

Typicaily, an application that invokes and controis the task-swapper calis the 
Init swapper cali-out function (rather than the task-swapper itseif). For 
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example, the DOS 5.0 Shell calls the Init swapper call-out function during Its 
Initialization, before it starts the DOS task-swapper that actually performs the 
session swapping. If any client fails the Init swapper call (that Is, returns 
with a nonzero value In AX), the Shell disables Its task-swapping option. 

Other task-swapping applications may terminate if a client fails this function. 

If any client fails the Init swapper call-out function call, all clients may receive 
a call to the swapper Exit call-out function, Including the client that failed the 
Init swapper call. As a result clients can receive a swapper Exit call without 
first receiving a corresponding swapper Init call. Clients can ignore this 
swapper Exit call. 

Query Suspend 

This call-out function to client programs notifies them that the task-swapper 
is preparing to perform a session swap. 

For Example: 

CMP AX,1 ;Query Suspend check from the task-swapper 

JA CHECK_NEXT_FUNCTION 

CMP BX,0UR_SESSI0N_ID ;BX has the current session ID 


Interrupts are enabled 
Calls to DOS can be made 

ES:DI = The call-out address of the calling task-swapper 


MOV AX,SWAP_FLAG 

CMP AX,0 

JE RETURN_TO_CALLER 


;Determine that the API is not being handled by another, 

; more competent client 

MOV AX, 6 

MOV BX,ID 

CALL 0UT_T0_SWAPPER 

;Does the most capable client have the same address as this client? 


CMP OFFSET API_INFO_STRUC,BX 

ONE 0THER_CLIENT_T0_HANDLE 

MOV AX,1 

JMP RETURN_TO_CALLER 

0THER_CLIENT_T0_HANDLE: 


Call-out to swapper for most capable 
API handler 

ID value of the asynchronous API 
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XOR AX, AX 

RETURN_TO_CALLER: 

RET 


SWAP_FLAG DB 0 


CHECK_NEXT_FUNCTION: 


0 if a session swap can be performed safely 

1 if the client cannot safely handle a session 
swap. All other values are reserved 

All other registers must be preserved. 


Comments 

A task-swapper calls this function when a session swap has been requested. 
The client can prevent the session swap, or It can perform any operation 
needed to allow the swap before returning. 

A global client can use the current session ID to identify the session that will 
be suspended when the session swap occurs. It can use this ID to maintain 
Information about the session when it is suspended and to restore the 
information when the session is resumed. The session ID Is an arbitrary 
value provided by the task-swapper; the values are not necessarily 
sequential and values may be reused after a session Is destroyed. A client 
can call the Test Memory Region task-swapper function to determine 
whether specific code or data in memory will be affected by the session 
swap and determine whether to allow the session swap. For example, a 
network redirector could run through a chain of outstanding request 
descriptors and, using the Test Memory Region function, check to see if any 
of the buffers or call-back addresses are located In local memory. If any are 
In local memory, the redirector could prevent the session swap or invoke 
special code to handle the case. 

Before a client prevents a session swap because of the state of an 
asynchronous API, It calls the Query API Support call-in function to ensure 
that the API Is not being handled by another, more competent client. If any 
client falls the Query Suspend function call, all clients may receive a call to 
the Session Active call-out function. Including the client that failed the Query 
Suspend call. As a result, clients can receive a Session Active call without 
first receiving a corresponding Query Suspend or Suspend Session call. 
Clients can Ignore this Session Active call. 
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Suspend Session 

This call-out function notifies clients that a session swap is about to take 
place. This is the last opportunity provided to a client to prevent the session 
swap. 

For Example: 

CMP AX, 2 ;Suspend Session notification? 

JA CHECK_NEXT_FUNCTION ; 

CMP BX,OUR_SESSION_ID ;BX has the current session ID 

;ES:DI = The call-out address of the calling task-swapper 
; Interrupts are disabled 


MOV AX,SWAP_FLAG 

CMP AX,0 

JE RETURN_TO_CALLER 

;Determine that the API is not being handled by another, 

; more competent client 

MOV AX, 6 ;Call-out to swapper 

MOV BX,ID ;ID value of the asynchronous API 

CALL 0UT_T0_SWAPPER 

CMP OFFSET API_INFO_STRUC,BX 


;Does the most capable client have the same address as this client? 

JNE OTHER_CLIENT_TO_HANDLE 
MOV AX,1 

JMP RETURN_TO_CALLER 

OTHER_CLIENT_TO_HANDLE: 

XOR AX, AX 

RETURN_TO_CALLER: 

RET 


SWAP_FLAG DB 0 


CHECK_NEXT_FUNCTION: 


Equals 0 if a session swap can be performed safely 
Equals 1 if the client cannot safely handle a session 
swap. All other values are reserved 

All other registers must be preserved. 
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Comments 


If no client fails the Query Suspend function call, the task-swapper disables 
interrupts and calls the Suspend Session call-out function. This provides 
clients with a final chance to prevent the sessien swap. Clients cannot issue 
any software interrupts or make any calls that might enable interrupts. 

If all clients return with zere in AX, the task-swapper replaces the current 
interrupt vector table with a saved copy before enabling interrupts. The 
saved copy represents the global state present when the task-swapper first 
started. This guarantees that interrupt handlers local to the session being 
suspended will not be called after the Suspend Session call returns to the 
task-swapper and before the next sessien is activated. Local software 
cannot receive interrupts between the Suspend Session call and the Activate 
Session call. This ensures that local software cannot gain control on a 
hardware interrupt and make a call into global software before the global 
software receives the ID of the resumed session. However, global clients 
can receive interrupts after the Suspend Session call and before the next 
Activate Session call. During this period, global software should not assume 
the contents of nonglobal memory. The Test Memory Region task-swapper 
call-eut functien tests a bleck of memory to determine whether it is lecal or 
global. 

Before a client prevents a sessien swap because of the state of an 
asynchronous API, it calls the Query API Support call-out function to ensure 
that the API is not being handled by another, more competent client. If any 
client fails the Suspend Session call-in function call, all clients may receive a 
call to the Session Active call-in functien, including the client that failed the 
Suspend Sessien call. As a result clients can receive a Session Active call 
without first receiving a cerrespending Query Suspend or Suspend Session 
call. Clients can ignere this Session Active call. 

Activate Session 

This call-out function notifies clients that a session is about to become active. 
If the session is a previously-suspended session, it has been reinstalled in 
memory and includes its local memory and interrupt-vector table. However, 
interrupts are disabled and must remain disabled. 

For Example: 

CMP AX, 3 ;Activate Session call-in 

; Interrupts are disabled and must remain disabled. 

;Calls to DOS cannot be made 

JA CHECK_NEXT_FUNCTION 
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TEST CX,0 


;If Bit 0 is set, indicates a new session 


; if not set, session was previously 
; suspended and is now being resumed. 

JNZ TRACK_SESSION_IDS ;If global client update list 

;ES:DI = The call-out address of the calling task-swapper. 

XOR AX, AX ; for future extensibility 

RET ;A11 other registers are preserved. 

TRACK_SESSION_IDS: 

MOV [LIST_INDEX] ,BX ;BX = ID of session being activated 

INC LISTJNDEX 

INC LISTJNDEX 

RET 

CHECK_NEXT_FUNCTION: 

Comments 

Although interrupts may have been enabled at times while the session 
memory was being swapped (and global software may have continued to 
receive interrupts), no interrupts could have been received by local software. 
However, after the interrupt-vector table of the new session has been loaded 
it is possible that a hardware interrupt will occur as soon as interrupts are 
enabled. If interrupts were not disabled when the call is made, local 
software could receive the interrupt and make a call to global software. 
However, that software might not be able to handle it correctly because it 
had not received the new session ID. If this is a newly-created session being 
activated for the first time, the Activate Session call will be preceded by a 
Create Session call-out function call. 

Session Active 

This call-out function notifies clients that a session has become active. If the 
session is a previously-suspended session, it has been reinstalled in memory 
and includes its local memory and interrupt vector table. 

For Example: 


CMP 

AX, 4 

;Session Active call-in function 
; Interrupts are enabled 
;Calls to DDS can be made 

JA 

I 

I — 
X 

LU 

LU 

/UNCTIDN 
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;ES:DI = call-out address of the calling task-swapper. 


TEST CX,0 


JNZ TRACK_SESSION_IDS 

XOR AX, AX 

RET 


TRACK_SESSION_IDS: 

MOV [LISTJNDEX] ,BX 
INC LISTJNDEX 

INC LISTJNDEX 

XOR AX, AX 

RET 


;If Bit 0 is set, indicates a new session 
; if not set, session was previously 
; suspended and is now being resumed. 

;If global client update list 

;for future extensibility 

;A11 other registers are preserved. 


;BX = ID of session being activated 


;for future extensibility 


CHECK_NEXT_FUNCTION: 


Comments 

If any client fails a Query Suspend or Suspend Session call-out function call, 
all clients may receive a call to the Session Active call-out function, including 
the client that failed the Suspend Session call. As a result clients can 
receive a Session Active call without first receiving a corresponding Query 
Suspend or Suspend Session call. Clients can ignore this Session Active 
call. 

Create Session 

This call-out function notifies clients that the task-swapper is about to create 
a new session. 

For Example: 

CMP AX, 5 ;Create Session call-in function 

; Interrupts are enabled 
;Calls to DDS can be made 
JA CHECK_NEXT_FUNCTIDN 

;ES:DI = call-out address of the calling task-swapper. 

;BX = The session ID of the new session. 

MDV AX,CREATE_SESSIDN_FLAG 

RET 
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CREATE SESSION FLAG DB 0 


=0 New Session can be created 
=1 Client cannot handle a new session 
All other values are reserved 


Comments 

When a new session is going to be created the task-swapper issues the 
Create Session function enabling a client to prevent the session from being 
created. For example, global software that keeps Information for each 
session In a fixed-length data structure can fail the call If the structure does 
not have enough room for another session. The newly-created session may 
not be activated immediately, and other sessions can be created, destroyed 
and swapped before the new session becomes active. If any client fails the 
Create Session call-in function call, all clients may receive a call to the 
Destroy Session call-in function, including the client that failed the Create 
Session call. As a result, clients can receive a Destroy Session call without 
first receiving a corresponding Create Session call. Clients can Ignore this 
Destroy Session call. 

Destroy Session 

This function notifies clients that the task-swapper is destroying a session. 
For Example: 


CMP 

AX, 6 

; Destroy Session call-in function? 
; Interrupts are enabled 
;Calls to DOS can be made 

JA 

CHECK NEXT 

FUNCTION 


;ES:DI = call-out address of the calling task-swapper 
;BX = The session ID of the session being destroyed 

XOR AX, AX ; For future extensibility 

RET 

;A11 other registers are preserved. 


Comments 

A task-swapper calls the Destroy Session call-out function when a session is 
being destroyed. Typically this will occur when the application In the current 
session exits. However, the session manager that controls the task-swapper 
also can provide a way for the user to terminate a session while the 
application Is still running or Is suspended. As a result, the session being 
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destroyed is not necessarily the current session. If any client falls the Create 
Session call-in function call, all clients may receive a call to the Destroy 
Session call-in function, including the client that failed the Create Session 
call. As a result, clients can receive a Destroy Session call without first 
receiving a corresponding Create Session call. Clients can ignore this 
Destroy Session call. 

Swapper Exit 

This call-in function notifies global clients that the task-swapper is no longer 
active. 

For Example: 


CMP 

AX, 7 

; Notification task-swapper no longer active? 
; Interrupts are enabled 
;Calls to DOS can be made 

JA 

OUT OF 

FUNCTIONS 


;ES:DI = The call-out address of the calling task-swapper. 


TEST OTHER_SWAPPER_PRESENT,BX ;0ther swapper present? 

XOR AX, AX ;AX = 0 for future extensibility 

RET 

OTHER_SWAPPER_PRESENT EQU OOOOOOOIB 

; Bit 1 is set if no other active swappers 
; Bit 1 is not set if at least one task-swapper 
; remains after the calling task-swapper exits 
;A11 other bits are reserved and must be 0 

0UT_0F_FUNCTI0NS: 


Comments 

A task-swapper calls this function when it is no longer active as a 
task-swapper. This allows global software that performs extra processing to 
disable that processing and to coexist with the task-swapper. 

This function can be called by software that Invokes the actual task-swapper 
rather than by the task-swapper itself. For this reason the call-in address 
specified in ES:DI may differ from addresses passed with other call-out 
functions and may be NULL. 
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Appendix G. PC DOS 7 Viewer 

The PC DOS Viewer that is inciuded in PC DOS 7 is an oniine pubiication 
viewer facility. It allows the user to search for, view and print information in 
online books created by the IBM OS/2 Information Presentation Facility 
Compiler (IPFC). The books must have an extension of .INF and be in the IPF 
format. The PC DOS viewer supports a subset of the OS/2 IPF tags. 

There are online books supplied with PC DOS 7, they are: 

• PC DOS Command Reference (CMDREF.INF) 

• REXX Information (DOSREXX.INF) 

• PC DOS Error Message (DOSERROR.INF) 


Invoking the Viewer 

The PC DOS Viewer is invoked in one of two ways: 

1 . Command Line 

VIEW 

Launches the Viewer. A list of .INF files found in the same directory 
as VIEW.EXE is displayed for the user to ohoose a book. 

VIEW BOOKNAME 

Launches the Viewer and opens the specified book at the Table of 
Contents. 

Note: If the specified book is not in either the current directory or the 
same directory VIEW.EXE is in, a path must be specified. 

2. PC DOS 7.0 Tools Group in Windows 

Double cliok on the desired book icon to launch the Viewer and open the 
desired book at the Table of Contents. 


Uses of Online Documents 

The uses of online document's are many and various. For the application 
developer, the use of online documents is a boost in productivity, no longer 
does the developer need to create code to display the help text or the links 
from subject to subject or even the string search utilities - this all becomes 
part of the online dooument structure once it has been compiled. The final 
result becomes searchable via the PC DOS viewer and allows for instant 
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access from the search results to the referenced page. All of this provides a 
more consistent way of viewing help to the end-user. 

As another example of the online document's use, an administrator may 
provide the user with reference manuals for their particular company - this 
results In portable and quicker access to Information. 

The high use of online information Is very true for the OS/2 world, where 
most products shipped also have some form of online help or Information 
with them - this provided via the use of the Information Presentation Facility. 


Creating Online Documents 

The information that you wish to view via the PC DOS viewer must be 
prepared and compiled. The Information Presentation Facility compiler Is 
supplied with the OS/2 developers tool kit and only runs under OS/2. For 
additional Information regarding the IPF compiler please refer to the OS/2 
Tool kit documentation. The current OS/2 IPF manual is OS/2 Warp IPF 
Programming Guide, this is referenced in the preface section of this book. 

To prepare your source files so that they may be recognized by the IPF 
compiler, requires certain tags to be coded Into the source file. The 
following briefly describes the process of creating a viewable online 
document. 

The following is a simple example of using a single source file, that uses a 
limited number of tags, which will produce a usable online document: 

:userdoc. 

:docprof . 

: title. Online Example 
: hi. Introduction 

:p.This is the introduction chapter to the rest of the document. 

:euserdoc. 

The :userdoc. tag is always the first item in the source file. It Identifies the 
beginning of the IPF file. This tag is a signal to the IPF compiler to begin 
translating the tagged file. The :euserdoc. Is used to signal the end of the 
tagged document. 

Place the :docprof. (document profile) tag at the beginning of your source file 
after the luserdoc. tag and before any heading definitions. Use the toe (table 
of contents) attribute on the :docprof. tag to control the heading levels 
displayed in the Content window. For example. If you want only heading 
levels 1 and 2 to appear, the tagging Is: 
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:docprof toc=12. 


If no toc= value is specified, heading ievei 1 through 3 appear in the 
Contents window. 

Not to be confused with window tities, the text string specified with a :titie. 
tag is piaced into the titie bar of an on-line document. When the oniine 
document is dispiayed, the titie appears on the titie iine of the main window. 
The tagging iooks iike this: 

: title. Endangered Mammals 

The maximum iength of a titie string specified with a :titie. tag is 47 
characters, inciuding spaces and bianks. 

The titie tag provides a name for the online document, but is aiso used for 
tities of Heip windows. The titie appears in the titie bar of the main window. 
You usuaily piace the titie tag after the :docprof. tag. 

Every file must start with a :h1. (chapter heading) tag. Heading ievei 
sequences must not skip a ievei in the heading hierarchy. For exampie, you 
cannot have a heading ievei 1 tag (:h1.) foiiowed by a heading ievei 3 tag 
(:h3.). 

You must have at ieast one paragraph tag (:p.) and associated text to 
dispiay a window. The foiiowing shows an IPF exampie source fiie: 

* 

:userdoc. 

: title. Endangered Mammals 

:hl res=001.The Manatee 
* 

:p. 

The manatee has a broad flat tail and two flipper 
like forelegs. There are no back legs. 

The manatee's large upper lip is split in two and 
can be used like fingers to place food into the 
mouth. Bristly hair protrudes from its lips, 
and almost buried in its hide are small eyes, with 
which it can barely see. 

* 

:euserdoc. 

It is a good idea to give your source fiie the extension of iPF, so that it may 
be distinguished from other fiies. The IPF compiler however, will append this 
extension if you do not specify a file extension when compiling. The 
following is the syntax that the IPF compiler will accept: 
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IPFC filename [/INF] [/S] [/X] [/W] [> messageoutputfilename] 


where: 

filename Specifies the name of your iPF source fiie or base file. If you do 
not give a file-name extension, the IPF compiler uses .IPF by 
default. If your file has a file-name extension other than IPF, 
include that file-name extension in the command line. 

/INF Compiles the source file as an online document. If this parameter 

is not included, the default is to compile the souroe file as a help 
library, whose extension is .FILP. 

IS Suppresses the performance of the Searoh function. This 

parameter increases compression of compiled data by about 10% 
to further reduce the storage it requires. 

/X Generates and displays a cross-reference list. 

/Wn Generates and displays a list of error messages. The n indicates 

the level of error messages you want to receive. Values you oan 
specify for n are 1, 2, or 3. For more information, see Interpreting 
IPFC Error Messages, that is supplied with the OS/2 tool kit. 

messageoutputfilename Specifies the name of the file where error and cross 
referenoe messages are sent. If you do not specify this 
parameter, messages generated by /X and /Wn are sent to the 
display screen. 

The IPF compiler is run from an OS/2 command line, as in the following 
example: 

C:>IPFC MYFILE.IPF /INF 

Files that may be viewed with either the PC DOS viewer or the OS/2 viewer, 
need to have the /INF option specified. This file is portable across both 
operating systems but, the following section describes functions and tags 
whioh should not be used if the online document is to be used with the PC 
DOS viewer. 


IBM OS/2 Functions and Tags not Supported by DOS 

The following major functions are not currently supported by the PC DOS 
Viewer: 

• Bookmarks 

• Viewed Pages 

• Libraries 
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• Graphics and hypergraphics 

• Hyperiinks between books 

• Launching of tutoriais/appiications 

• Customized windows/controis 

AM tags and aii tag options may not be supported by the PC DOS Viewer. 

The foilowing tabie describes the tags supported by DOS and any limitations, 
if applicable. 


Tag 

End Tag 

Exceptions (if any) 

.br 



.* 



.im 



icaution. 

:ecaution. 


icgraphic. 

:ecgraphic. 


:color. 



:dl. 

:edl. 


idocprof. 


Only the toc= attribute is supported 

:fig. 

:efig. 


ifigcap. 



:fn. 

:efn. 


:h1. - :h6. 


Only the following attributes are supported: 
res = , id = , name = , toc=, nosearch and hide 

:hp1 . - :hp9. 

:ehp1 . - 
:ehp9. 

hpx, where x = 1 , 2, 3, 5, 6 or 7 will result in 
the string being displayed in the default font. 
Italicized strings will be enclosed in quotation 
marks. 

:i1. - :i2. 


Only the following attributes are supported: 
id = , roots = , sortkey= and refid = 

:isyn. 



:li. 



dink. 

:elink. 

Only the following attributes are supported: 
reftype= and reftype = fn 

:ln 



:lp 



mote. 



:nt. 

:ent. 
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Tag 

End Tag 

Exceptions (if any) 

:ol. 

:eol. 


:P- 



:parml. 

:eparml. 


:pd. 



:pt. 



:rnn. 



:sl. 

:esl. 


:table. 

:etable. 


:title. 



:ul. 

:eul. 


:userdoc. 

:euserdoc. 


:warning. 

:ewarning. 


:xnnp. 

:exnnp. 



Again, please be aware that additional information may be found in the OS/2 
tool kit publications. 
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Appendix H. Miscellaneous Control Blocks 


This section identifies the structure and content of some control blocks 
referenced throughout this document. 


DPB - Disk Parameter Block Definition 


DPB structure: 




dpb STRUC 

dpb drive 

DB 

? 

; Logical drive # assoc with DPB (A=0,B=1, . . . ) 

dpb_UNIT 

DB 

7 

; Driver unit number of DPB 

dpb_sector_size 

DW 

7 

; Size of physical sector in bytes 

dpb_cl uster_niask 

DB 

7 

; Sectors/cluster - 1 

dpb_cl uster_shi ft 

DB 

7 

; Log2 of sectors/cluster 

dpb_f i rst_EAT 

DW 

7 

; Starting record of FATs 

dpb_EAT_count 

DB 

7 

; Number of EATs for this drive 

dpb_root_entries 

DW 

7 

; Number of directory entries 

dpb_fi rst_sector 

DW 

7 

; first sector of first cluster 

dpb_max_cl uster 

DW 

7 

; Number of clusters on drive + 1 

dpb_EAT_si ze 

DW 

7 

; Number of records occupied by EAT 

dpb_di r_sector 

DW 

7 

; Starting record of directory 

dpb_driver_addr 

DD 

7 

; Pointer to driver 

dpb_niedia 

DB 

7 

; Media byte 

dpb_fi rst_access 

DB 

7 

; This is initialized to -1 to force a media 
; check the first time this DPB is used 

dpb_next_dpb 

DD 

7 

; Pointer to next Drive parameter block 

dpb_next_free 

DW 

7 

; Cluster # of last allocated cluster 

dpb free cnt 
dpb ENDS 

DW 

7 

; Count of free clusters, -1 if unknown 


DPBSIZ EQU SIZE dpb ; Size of the structure in bytes 

DSKSIZ = dpb_niax_cl uster ; Size of disk (temp used during init only) 
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BPB - BIOS Parameter Block Definition 

This structure is used to buiid a fuii DPB. 


BPBLOCK STRUC 
BPSECSZ DW 
BPCLUS DB 
BPRES DW 
BPFTCNT DB 
BPDRCNT DW 
BPSCCNT DW 
BPMEDIA DB 
BPFTSEC DW 
BPBLOCK ENDS 

A_BPB STRUC 

BPB_BYTESPERSECTOR DW ? 

BPB_SECTORSPERCLUSTER DB ? 

BPB_RESERVEDSECTORS DW ? 

BPB_NUMBEROFFATS DB ? 

BPB_ROOTENTRIES DW ? 

BPB_TOTALSECTORS DW ? 

BPB_MEDIADESCRIPTOR DB ? 

BPB_SECTORSPERFAT DW ? 

BPB_SECTORSPERTRACK DW ? 

BPB_HEADS DW ? 

BPB_HIDDENSECTORS DW ? 

DW ? 

BPB_BIGTOTALSECTORS DW ? 

DW ? 

DB 6 DUP(?) 

A BPB ENDS 


SIZE IN BYTES OF PHYSICAL SECTOR 

SECTORS/ALLOC UNIT 

NUMBER OF RESERVED SECTORS 

NUMBER OF FATS 

NUMBER OF DIRECTORY ENTRIES 

TOTAL NUMBER OF SECTORS 

MEDIA DESCRIPTOR BYTE 

NUMBER OF SECTORS TAKEN UP BY ONE FAT 
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CDS - Current Directory Structure 

CDS items are used by the internal routines to store cluster numbers and 
network Identifiers for each logical drive. The ID field Is used dually, both as 
net ID and for a cluster number for local devices. In the case of local 
devices, the cluster number will be -1 If there is a potential of the disk being 
changed or If the path must be recracked. The END field is the location of 
the end of the definition. 


DIRSTRLEN 

EQU 

64+3 

; Max length in bytes of directory 

TEMPLEN 

EQU 

DIRSTRLEN*2 



curdir list STRUC 


curdi r_text 

DB 

DIRSTRLEN DUP (?) 

; text of assignment and curdir 

curdir_flags 

DW 

7 

various flags 

curdi r_devptr 

DD 

7 

local pointer to DPB or net device 

curdi r_ID 

DW 

7 

cluster of current dir (net ID) 


DW 

7 


curdir user word DW 

7 


curdi r_end 

DW 

7 

end of assignment 

curdi r_type 

DB 

7 

IPS drive (2=ifs, 4=netuse) 

curdi r_i fs_hdr 

DD 

7 

Ptr to File System Header 

curdi r_fsda 

DB 

2 DUP (?) ; 

File System Dependent Data Area 

curdi r_li St ENDS 



curdi rLen 

EQU 

Size curdi r_l i st 

; Needed for 




; ASM87 which doesn't allow 




; Size directive as a macro 




; argument 

curdi r_netID 

EQU 

DWORD PTR curdi r_ 

ID 

;Elag word masks 




curdi r_i snet 

EQU 

lOOOOOOOOOOOOOOOB 


curdi r_isi fs 

EQU 

lOOOOOOOOOOOOOOOB 

; DOS 4.0 

curdi r_i nuse 

EQU 

OlOOOOOOOOOOOOOOB 


curdi r_spl ice 

EQU 

OOlOOOOOOOOOOOOOB 


curdi r_local 

EQU 

OOOIOOOOOOOOOOOOB 



Purpose: 

Maps drive letter to physical device and provide a way to keep traok of each 
directory for each drive. 
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SFT - System File Table 

System File Table structures: 


SF 

STRUC 



SFLi nk 

DD 

? 


SFCount 

DW 

7 ; 

; number of entries 

SFTable 

DW 

7 ; 

; beginning of array of the following 

SF 

ENDS 



; system file 

table entry 



sf_entry 

STRUC 



sf_ref_count DW 

7 

number of processes sharing entry 




if FCB then ref count 

sf_mode 

DW 

7 ; 

mode of access or high bit on if FCB 

sf_attr 

DB 

7 ; 

attribute of file 

sf_fl ags 

DW 

7 ; 

Bits 8-15 


Bit 15 = 1 if remote file 

= 0 if local file or device 
Bit 14 = 1 if date/time is not to be 
set from clock at CLOSE. Set by 
FILETIMES and ECB_CL0SE. Reset by 
other reseters of the dirty bit 
(WRITE) 

Bit 13 = Pipe bit (reserved) 

Bits 0-7 (old FCB_devid bits) 

If remote file or local file, bit 
6=0 if dirty Device ID number, bits 
0-5 if local file, 
bit 7=0 for local file, bit 7 
=1 for local I/O device 
If local I/O device, bit 6=0 if EOF (input) 

Bit 5=1 if Raw mode 

Bit 0=1 if console input device 

Bit 1=1 if console output device 

Bit 2=1 if null devi ce 

Bit 3=1 if clock device 


sf_devptr 

DD 

7 


Points to DPB if local file, points 
to device header if local device, 
points to net device header if remote 

sf_fi rcl us 

DW 

7 


First cluster of file (bit 15 = 0) 

sf_time 

DW 

7 


Time associated with file 

sf_date 

DW 

7 


Date associated with file 

sf_size 

DD 

7 


Size associated with file 

sf_position 

DD 

7 


Read/Write pointer or LRU count for FCBs 

Starting here. 

the next 

7 bytes may be 

used by the file system to store an ID 

sf_cluspos 

DW 

7 


Position of last cluster accessed 

sf_di rsec 

DD 

7 


Sector number of directory sector for this fil 

sf dirpos 

DB 

7 


Offset of this entry in the above 

End of 7 bytes of file-system specific 

info. 

sf_name 

DB 

11 DUP (?) 


11 character name that is in the 


directory entry. This is used by 
close to detect file deleted and 
disk changed errors. 
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; SHARING INFO 


sf chain 

DD 

? 


; link 

to next SF 

sf UID 

DW 

? 




sf PID 

DW 

? 




sf_MFT 

DW 

? 




sf Istclus 

DW 

? 


; Last 

cluster accessed 

sf_IFS_HDR 

DD 

? 




entry 

ENDS 





sf_fsda 

EQU 

BYTE 

PTR 

sf_cl uspos 

;D0S 4.0 

sf_seri al_ID 

EQU 

WORD 

PTR 

sf_firclus 

;D0S 4.0 

sf_neti d 

EQU 

BYTE 

PTR 

sf_cl uspos 


sf OpenAge 

EQU 

WORD 

PTR 

sf_position+2 


sf_LRU 

EQU 

WORD 

PTR 

sf_position 



sf_defaul t_nuniber EQU 5h 

; Note that we need to mark an SET as being busy for OPEN/CREATE. This is 
; because an INT 24 may prevent us from 'freeing' it. We mark this as such 
; by placing a -1 in the ref_count field. 
sf_busy EQU -I 

; mode mask for FOB detection 


sf_i sfcb 

EQU 

lOOOOOOOOOOOOOOOB 


Flag word masks 





sf_i snet 

EQU 

lOOOOOOOOOOOOOOOB 


sf_close_nodate 

EQU 

OlOOOOOOOOOOOOOOB 


sf_pipe 

EQU 

OOlOOOOOOOOOOOOOB 


sf_no_inherit 

EQU 

OOOIOOOOOOOOOOOOB 


sf_net_spool 

EQU 

OOOOIOOOOOOOOOOOB 


Handl e_Fai 1_I24 

EQU 

OOOOOOOIOOOOOOOOB 

;BIT 8 - DISK FULL 124 ERROR 

Local file/device flag 

masks 




devid_file_clean 

EQU 

40h 

true if 

file and not written 

devi d_f i 1 e_mask_dri ve 

EQU 

3 Eh 

mask for drive number 

devid_device 

EQU 

80h 

true if 

a device 

devid_device_EOF 

EQU 

40h 

true if 

end of file reached 

devid_device_raw 

EQU 

20h 

true if 

in raw mode 

devi d_devi ce_speci al 

EQU 

lOh 

true if 

special device 

devid_device_clock 

EQU 

08h 

true if 

clock device 

devid_device_nul 1 

EQU 

04h 

true if 

null device 

devi d_devi ce_con_out 

EQU 

02h 

true if 

console output 

devi d_devi ce_con_i n 

EQU 

Olh 

true if 

consle input 
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structure of devid field as returned by lOCTL is: 
BIT 7 6 5 4 3 2 1 0 



= 0 if this channel is a disk file 
If ISDEV = 1 

EOF = 0 if End Of Eile on input 

RAW = 1 if this device is in Raw mode 

= 0 if this device is cooked 

ISCLK = 1 if this device is the clock device 

ISNUL = 1 if this device is the null device 

ISCOT = 1 if this device is the console output 

ISCIN = 1 if this device is the console input 

If ISDEV = 0 

EOF = 0 if channel has been written 
Bits 0-5 are the block device number for 
the channel (0 = A, 1 = B, ...) 
devid_ISDEV EQU 80h 

devid_E0F EQU 40h 

devid_RAW EQU 20h 

devid_SPECIAL EQU lOH 

devid_ISCLK EQU 08h 

devid_ISNUL EQU 04h 

devid_ISCQT EQU 02h 

devid_ISCIN EQU Olh 

devid_block_dev EQU lEh ; mask for block device number 
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Buffer Header - Disk I/O Buffer Header 

Field definition for I/O buffer information: 


BUFFINFO 
buf_next 
buf_prev 
buf ID 


buf_fl ags 


Pointer to next buffer in list 
Pointer to prev buffer in list 
Drive of buffer (bit 7=0) 

SFT table index (bit 7=1) 

= FFH if buffer free 
Bit 7 = 1 if Remote file buffer 
= 0 if Local device buffer 
Bit 6 = 1 if buffer dirty 
Bit 5 = Reserved 
Bit 4 = Search bit (bit 7 = 1) 

Bit 3 = 1 if buffer is DATA 

Bit 2 = 1 if buffer is DIR 

Bit 1 = 1 if buffer is FAT 

Bit 0 = Reserved 


buf_sector 

DD 

? 

; Sector number of buffer (bit 7 = 0) 

; The next two 

items are 

often refed as a 

word (bit 7 = 0) 

buf wrtcnt 

DB 

? 

; Eor EAT sectors, # times sector written out 

buf wrtcntinc DW 

? 

; " " " , # sectors between each write 

buf_DPB 

DD 

7 

; Pointer to drive parameters 

buf_fil 1 

DW 

7 

; How full buffer is (bit 7 = 1) 

buf reservet 

DB 

7 

; make DWORD boundary for 386 

BUFFINFO 

ENDS 



buf_offset 

EQU 

DWORD PTR buf_ 

sector 


For bit 7 = 1, this is the byte 
offset of the start of the buffer in 
the file pointed to by buf_ID. Thus 
the buffer starts at location 
buf_offset in the file and contains 
buf_fill bytes. 


BUFINSIZ 

EQU 

SIZE BUEFINFQ 

buf_Free 

EQU 

OFEh 

;Flag byte masks 

buf_isnet 

EQU 

lOOOOOOOB 

buf dirty 

EQU 

OlOOOOOOB 

. *** 

buf visit 

EQU 

OOlOOOOOB 

. *** 

buf_snbuf 

EQU 

OOOIOOOOB 

buf_isDATA 

EQU 

OOOOIOOOB 

buf_isDIR 

EQU 

OOOOOIOOB 

buf_isFAT 

EQU 

OOOOOOlOB 

buf_type_0 

EQU 

IIIIOOOIB 

buf_NetID 

EQU 

BUFINSIZ 


; Size of structure in bytes 
; buf_id of free buffer 


; AND sets type to "none" 


Buffer Hash Entry Structure 

BUFFER_HASH_ENTRY STRUC 

EMS PAGE NUM DW -1 


DOS 4.0 

logical page number for EMS handle 
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BUFFER BUCKET DD 

7 

; pointer to buffers 

DIRTY COUNT DB 

0 

; number of dirty buffers 

BUFEER RESERVED DB 

0 

; reserved 

BUFFER_HASH_ENTRY 

ENDS 


MaxBuffinBucket EQU 

15 

; Max number of buffers per bucket 

MaxBucketinPage EQU 

2 

; Max number of buckets per 16kb page 
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storage Header - Memory arena structure 


; arena item 

arena STRUC 

arena_signatijre DB ? 

arena_owner DW ? 

arena_size DW ? 

arena_reserved DB 3 DUP{?) 

arena_nanie DB 8 DUP(?) 

arena ENDS 

arena_owner_system EQU 0 
arena_signature_normal EQU 4Dh 
arena_signature_end EQU 5Ah 


4D for valid item, 5A for last item 

owner of arena item 

size in paragraphs of item 

reserved 

owner file name 


; free block indication 
; valid signature, not end of arena 
; valid signature, last block in arena 
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Index 


Special Characters 

/INF 358 

Numerics 

32MB, media greater than 112 
8086/8088 code rules 49 

A 

absolute disk read/write (INT 25H/26H) 112 

AC flag set condition 70 
Access, Lock/Unlock File 253 
Accessing POWER.EXE Controls 122 
accessing the disk 7 
accumulator register 136 
address (INT 22FI), terminate 107 
address (INT 23H), Ctrl - Break exit 108 
address, default disk transfer 38 
address, memory map 34 
Address, Set Disk Transfer 168 
AL function values 273 
allocate command, EMS 79 
Allocate Memory 227 
Allocated Memory Blocks (SETBLOCK), 
Modify 229 

Allocated Memory, Free 228 
Allocation Table Information 169 
Allocation Table Information for Specific 
Device 170 

ARM Error Return Codes 129 
APPEND 129 
application swapping 325 
arena structure, Memory 369 
ASCII in Dump command 53 
ASCII mode, I/O in 32 
ASCIIZ filename string 15 
Assemble command 49 
Assembler Language, IBM PC 136 
attribute field 87 
attribute, file 17 


auxiliary carry flag 70 
Auxiliary Input 145 
Auxiliary Output 146 

B 

base pointer 137 

base register 136 

binary mode, I/O in 32 

BIOS parameter block (BPB) 86, 97 

BIOS Parameter Block Definition 362 

bit fields 209 

Block Definition, BIOS Parameter 362 
Block Definition, Disk Parameter 361 
block device driver 85 

BIOS parameter block (BPB) array 86 
drive letters 85 
input/output request 100 
installing a block device 86 
installing a character device 86 
media descriptor byte 86 
random I/O 85 
Block Read, Random 179 
Block Write, Random 181 
block, parameter 39 
Blocks, Control 361 
blocks, memory 33 
book, organization of this 1 
boot record 7 

boot record, extended BPB 99 
boot sector format of BPB 98 
BP (base pointer) 137 
BPB 362 

BPB (see BIOS parameter block) 

Buffer Pleader 367 

buffer memory (disk transfer area) 26 
Buffered Keyboard Input 152 
build BPB request 97 
boot sector format 98 
extended boot record 99 
extended BPB structure 98 
media type 98 
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busy bit 91 

byte, media descriptor 95 
bytes in a request header 90 
bytes in directory entry 17 

c 

CALL FAR 110 

caiis for code page switching 282 

caiis, using PC DOS 7 function 135 

Caiiup/Down Register Structure 323 

cancei aii fiies 1 1 6 

cancei fiie 1 1 6 

Cancei Redirection 263 

carry fiag 70 

CDS 363 

Change Current Directory (CHDiR) 206 
Change Fiie Mode (CHMOD) 221 
character device driver 85 

instaiiing a new CON device 86 
output request 102 
terminating the input queue 102 
type-ahead input buffer 102 
character input/output fiush request 102 
character input/output status 101 
Check DOSDOCK instaiiation 118 
Check Standard input Status 153 
check, ctri-break 195 
Check, DOS Protected Mode Services 119 
CHECKSUM 40 
ciear condition of fiag 70 
Ciear Keyboard Buffer and invoke a Keyboard 
Function 154 
ciock device bit 89 
Ciose a Fiie Handie 214 
CLOSE caii 103 
Ciose Fiie 158 
ciuster number, first 20 
ciuster, sectors per 10 
Code of a Subprocess (WAiT), Get a 
Return 234 

code page switching 282 
Code Page, Get/Set Giobai 268 
code segment 137 
code, interrupt 2FH function 115 
codes (iNT 24H). error 109 


Codes, APM Error Return 129 
Codes, DPMS Error Return 323 
codes, extended error 138 
COM fiies 11 
COM programs 136 
command code 91 

command fiies from /S format option 11 

command iine 40 

command processor 41 

COMMAND.COM 11,33 

Commit Fiie 270 

communication area 34 

Compare command 51 

compatibiiity mode 210 

computer name 256 

CONFiG.SYS 93 

Consoie i/0, Direct 148 

Consoie input with Echo 143 

Consoie input without Echo 150 

controi biock 33 

Controi Biocks 361 

Controi for Devices, i/0 223, 273 

controi strings 88 

controi vaiues, i/0 32 

controi-break routine 42 

count register 136 

Country Dependent information, Get or Set 201 
Country Information, Get Extended 265 
Create a Fiie 207 
Create Fiie 165 
Create New Fiie 252 
Create Subdirectory (MKDIR) 204 
Create Unique Fiie 250 
Creating Oniine documents 356 
criticai error handier vector (INT 24H) 108 

CALL FAR 110 
device header format 112 
disk error 1 10 
error codes 109 
FAiL request 1 1 2 
hardware error 108 
IGNORE request 1 1 2 
ignore response 110 
IRET execution 109 
criticai error situation 42 
CS register 137 
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ctrl-break checking 195 

Ctrl-Break routine 42 

Ctri - Break exit address (iNT 23H) 108 

Current Directory Structure 363 

Current Directory, Get 226 

Current Disk 167 

Current Dock Status, Get 118 

CY fiag set condition 70 

D 

data area 12 
data fiies, storage of 12 
data register 136 
data segment 137 
Date and Time, Get/Set Fiie's 242 
date in a directory structure 20 
Date, Get 185 
Date, Set 186 
date, system 44 
DBCS vector 267, 285 
deaiiocate command, EMS 80 
DEBUG.COM utiiity 45 
Definition, BiOS Parameter Biock 362 
Definition, Disk Parameter Biock 361 
Deiete a Fiie from a Specified Directory 
(UNLiNK) 218 
Deiete Fiie 162 
denynone mode 212 
DenyRead mode 211 
DenyRead/Write mode 211 
DenyWrite mode 21 1 
descriptor byte, media 95 
destination index 137 
detect POWER.EXE 122 

Detecting the Expanded Memory Manager 310 
device driver controi channei 31 
device driver header 87 
attribute fieid 87 
ciock device bit 89 
controi strings 88 
definition of 87 
format of 87 
input device, standard 89 
iOCti bit 88 
name/unit fieid 89 
next device header fieid 87 


device driver header (continued) 

NUL device 89 

open/ciose removabie media bit 88 
output device, standard 89 
pointer to interrupt routine 89 
pointer to strategy routine 89 
device driver, EMS 301 
device fiie handie, standard 16 
device header format (iNT 24H) 112 

device, iocai or remote 281 
Device, Redirect 261 
DeviceAttributes fieid 290 
DeviceBPB fieid 290 
Devices, i/0 Controi for 223, 273 
DeviceType fieid 289 
Di fiag ciear condition 70 
Di register 137 
direct access to media 112 
Direct Consoie i/0 148 

Direct Consoie input without Echo 149 
direction fiag 70 

Directory (CHDiR), Change Current 206 
Directory Structure, Current 363 
Directory, Get Current 226 
directory, root 1 1 
disk accessing 7 
disk format 7 
boot record 7 
data area 12 
disk directory 1 1 
fiie aiiocation tabie (FAT) 10 
root directory 1 1 
Disk Free Space, Get 199 
Disk i/0 Buffer Header 367 
disk i/0 warning 1 13 
Disk Parameter Biock Definition 361 
Disk Reset 155 

Disk Transfer Address (DTA), Get 190 

Disk Transfer Address, Set 168 

disk transfer area (DTA) 26 

Disk, Current 167 

Disk, Seiect 156 

DiSKCOMP utiiity 45 

Dispiay Output 144 

Dispiay String 151 

DN fiag set condition 70 
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Docking Event, Get 118 
done bit 91 

DOS Protected Mode Services Check 119 
DOSDOCK APi 118 
DOSDOCK instaiiation, Check 118 
doubie quotation (“) 55 

DPB 361 

DPB Structure 171, 193 
DPMS 

Aiiocate Biock of Extended Memory 320 
Aiiocate Descriptors 316 
Buiid Aiias to Reai-Mode Segment 318 
Cali Protected-Mode Procedure 314 
Call Real-Mode Procedure (IRET) 315 
Call Real-Mode Procedure (RETF) 315 
Call Real-Mode Procedure Interrupt 
Handler 316 

Create Alias Descriptor 317 
Free a Descriptor 317 
Free Block of Extended Memory 320 
Get Descriptor Base 319 
Get Size of Largest Free Block of 
Memory 320 
Installation Check 314 
Map Linear Memory 321 
Relocate Segment to Extended Memory 322 
Set Descriptor Base 318 
Set Descriptor Limit 319 
Set Descriptor Type/Attribute 319 
Unmap Linear Memory 321 
DPMS Error Return Codes 323 
DS register 137 
DTA (see disk transfer area) 

Dump command 52 

Duplicate a File Handle (DUP) 224 

DYNALOAD 86 

E 

Echo, Console Input with 143 
Echo, Console Input without 150 
Echo, Direct Console Input without 149 
El flag set condition 70 

ejecting media from drive control strings 278 
EMM 

Allocate Pages 306 
Deallocate Pages 308 


EMM (continued) 

Get EMM Version 309 

Get Page Frame Address 304 

Get Status 303 

Get Unallocated Page Count 305 
Map Handle Page 307 
EMM Version, Get 309 
EMS (see expanded memory specification) 
EMS-capable hardware adapter 301 
enable/disable device power state (1.1) 126 

end of status 1 1 7 

engage/disengage power management 
(1.1) 127 

Enter command 55 
Entry, Search for First 159 
Entry, Search for Next 161 
environment string, subprogram 39 
error bit 91 

error code information 138 

error codes, status word 91 

error handler vector (INT 24H), critical 108 

Error Return Codes, APM 129 

Error Return Codes, DPMS 323 

Error, Extended 248 

ES register 137 

EXE extension, DEBUG 48 

EXE programs 38 

Execute a Program (EXEC), Load or 230 
executing a subprogram 39 
exit program 107 

Expanded Memory Manager, Detecting 310 

expanded memory specification (EMS) 301 

extended 25H or 26H 112 

extended BPB structure 98 

Extended Country Information, Get 265 

extended error codes 138 

Extended Error, Get 248 

extended file control block 26 

Extended Open/Create 271 

extra segment 137 

F 

FAIL request 1 1 2 
failures, print 117 
FAR prefix, DEBUG 50 
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FAT (see file allocation table) 

FCB (see file control block) 

FOBS command 27 
field in parameter block 288 
fields in device header 87 
File (FIND FIRST), Find First Matching 235 
File (FIND NEXT), Find Next Matching 237 
File Access, Lock/Unlock 253 
file allocation table (FAT) 10 
file attribute 17 
file control block (FCB) 23 
extended 26 
format 24 

logical record size 25 
opened file 23 
record number 25 
reserved fields 23 
unopened file 23 
file control block structure 23 
File Flandle (DUP), Duplicate a 224 
File Flandle, Close a 214 
file handles 16 

file sharing using SHARE command 27 

File Size 175 

file system activities 30 

File Table, System 364 

File's Date and Time, Get/Set 242 

file, cancel 1 1 6 

File, Close 158 

File, Commit 270 

File, Create 165 

File, Create New 252 

File, Create Unique 250 

File, Delete 162 

File, Open 157 

File, Open a 208 

File, Rename 166 

File, Rename a 241 

file, submit 1 1 6 

Filename, Parse 183 

FILES command 16 

files, cancel all 116 

files, physical location of 10 

Fill command 57 

Find First Matching File (FIND FIRST) 235 
Find Next Matching File (FIND NEXT) 237 


first block device driver 85 

First Matching File (FIND FIRST), Find 235 

flags 136 

flags in register command 70 

flags, display 69 

flush function call parameter 102 

Force a Duplicate of a Handle (FORCDUP) 225 

format option, /S 1 1 

format/verify a track 293 

fragments, program code 136 

Free Allocated Memory 228 

function calls, using PC DOS 7 135 

function code, interrupt 2FH 115 

function dispatcher, PC DOS 7 38 

function request (INT 21 H) 107 

G 

general registers, list of 136 
generic lOCtI request 287 
format/verify a track 293 
get device parameters 288 
read track on a logical device 292 
set device parameters 288 
verify a track 293 
write track on a logical device 292 
Get a Return Code of a Subprocess (WAIT) 234 
Get Allocation Strategy 243 
Get Current Directory 226 
Get Current Dock Status 118 
Get Date 185 
Get Default DPB 171 
get device information 274 
get device parameters 288 
Get Device Power State (1.1) 125 

Get Disk Free Space 199 
Get Disk Transfer Address (DTA) 190 
Get Docking Event 118 
Get DPB 193 

Get Extended Country Information 265 

Get Extended Error 248 

Get InDOS Flag Address 197 

get installed state 1 1 6 

Get Interrupt Vector 198 

get logical device function call 104 

Get Machine Name 256 
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Hexarithmetic command 60 


get or set APM polling period 128 

Get or Set Country Dependent Information 201 

get or set idle detection strategy 123 

get or set POWER saving level 124 

get or set power status 122 

Get or Set System Value 195 

Get PC DOS 7 Version Number 191 

Get Printer Setup 258 

Get Program Segment Prefix Address 264 

Get PSP Address 239 

Get Redirection List Entry 259 

get statistics 127 

Get Time 1 87 

Get Upper-Memory Link 246 
Get Verify Setting 240 
Get/Set File's Date and Time 242 
Get/Set Global Code Page 268 
Global Code Page, Get/Set 268 
Go command 58 

H 

Handle (FORCDUP), Force a Duplicate of a 225 
Handle Count, Set 269 
handle is local or remote 281 
handler vector (INT 24H), critical error 108 
handler, installing a 132 
handles, file 16 
hard error on disk 1 1 0 
header, device driver 87 
attribute field 87 
clock device bit 89 
control strings 88 
definition of 87 
format of 87 
input device, standard 89 
lOCtI bit 88 
name/unit field 89 
next device header field 87 
NUL device 89 

open/close removable media bit 88 
output device, standard 89 
pointer to interrupt routine 89 
pointer to strategy routine 89 
HEX extension, DEBUG 48 
hexadecimal in Dump command 53 


I 

I/O Buffer Header, Disk 367 
I/O Control for Devices (lOCtI) 273 
AL function values 273 
block device, read/write to a 277 
character device, read/write to a 276 
code page switching 282 
description of 273 
device is local or remote 280 
generic lOCtI request 287 
format/verify a track 293 
get device parameters 288 
read track on a logical device 292 
set device parameters 288 
verify a track 293 
write track on a logical device 292 
get device information 274 
handle is local or remote 281 
input device status 278 
lock conflicts 281 
logical drive check 296 
media lock or unlock, and eject 278 
output device status 278 
query device 298 
query handle 298 

removable media determination 279 
set device information 274 
set logical drive 297 
sharing and lock conflict retries 281 
IBM PC Assembler Language 136 
IBMBIO.COM 11 
IBMDOS.COM 11 
ignore response 110 
index register 137 
INF 355 

initialization request 93 
initializing a device driver 86 
input bit, standard 89 
Input command 61 
Input Status, Check Standard 153 
Input, Auxiliary 145 
input/output request 100 
installed state, get 1 1 6 
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installing device drivers 85 
installing the handler 132 
instruction pointer 137 
INT21 function call 135 
internal stack 137 
interrupt 21 H, issuing 135 
Interrupt 2FH Function AH=54H POWER.EXE 
control 120 

interrupt 2FFI function AX-530BFI PM event 
broadcast 120 

interrupt 2FFI function AX-530CFI PM event first 
phase broadcast 122 
interrupt flag 70 
interrupt routines 90 
build BPB request 97 
character input/output flush request 102 
character input/output status requests 101 
command code value 92 
generic lOCtI request 104 
get logical device request 104 
initialization request 93 
input/output request 100 
lOCtI query 105 
media check request 94 
media descriptor byte 95 
nondestructive input request 101 
open or close request 102 
removable media request 103 
request data structures 92 
request header 90 
set logical device request 105 
Interrupt Vector, Get 198 
Interrupt Vector, Set 177 
invalid responses 1 1 1 
lOCtI (see I/O Control for Devices) 
lOCtI bit 88 
lOCtI query 105 
lOCtI request, generic 104 
IP (instruction pointer) 137 
IPF 355 

IPF compiler 356 
IPFC 355 

IRET (return-from-interrupt instruction) 108 


K 

Keyboard Buffer and Invoke a Keyboard 
Function, Clear 154 
Keyboard Input, Buffered 152 

L 

LAN (see local area network) 

LIM (see Lotus/Intel/Microsoft) 

LIM specification 301 

List Entry, Get Redirection 259 

Load command 61 

Load or Execute a Program (EXEC) 230 

load time, identify program at 36 

loading a subprogram 39 

loading an overlay 41 

loading data using DEBUG 62 

local area network (LAN) 21 

local device, handle is 281 

local or remote device 280 

location of files on disk 10 

lock conflicts 281 

Lock/Unlock File Access 253 

locking media drive control strings 278 

logical device function call, get/set 104 

logical drive check 296 

logical record size 25 

logical sector numbers (LSN) 113 

Lotus/Intel/Microsoft (LIM) 301 

LSN (see logical sector numbers) 

M 

Machine Name, Get 256 
map command, EMS 80 
media >32MB 112 

media determination, removable 279 
media warning, removable 114 
MediaType field 290 
Memory arena structure 369 
memory blocks 33 
Memory Blocks (SETBLOCK), Modify 
Allocated 229 

memory buffer (disk transfer area) 26 
memory map address 34 
communication area 34 
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memory supported by PC DOS 7 301 

Memory, Allocate 227 
Memory, Free Allocated 228 
Mode (CHMOD), Change File 221 
Modify Allocated Memory Blocks 
(SETBLOCK) 229 
Move command 64 

Move File Read Write Pointer (LSEEK) 219 
multiplex (INT 2FH) 115 
APPEND 129 
install a handler 132 
interrupt 2FFI function code 115 
print error codes 1 1 6 

N 

NA flag clear condition 70 

name a file 15 

Name command 65 

Name, Get Machine 256 

name/unit field 89 

NAME = parameter 39 

National Language Support (NLS) 21 

NC flag set condition 70 

NEAR prefix, DEBUG 50 

network path 21 

network redirection 260 

NewName string 241 

next device header 87 

Next Entry, Search for 161 

Next Matching File (FIND NEXT), Find 237 

NG flag set condition 70 

NLS (see National Language Support) 

NLSFUNC DOS extension 266 

nondestructive input request 101 

NUL device 89 

numbering convention, register 137 
NumberOfCylinders field 290 
NV flag clear condition 70 
NZ flag clear condition 70 

o 

Open a File 208 

Open a File, matrix of 213 

OPEN call 103 


Open File 157 
open mode 209 
Open/Create, Extended 271 
opened file control block 23 
OS/2 Toolkit 356 
output bit, standard 89 
Output command 66 
Output, Auxiliary 146 
Output, Display 144 
Output, Printer 147 
output/input request 100 
OV flag set condition 70 
overflow flag 70 
overlay, loading an 41 

P 

paragraphs of memory 33 
Parameter Block Definition, BIOS 362 
Parameter Block Definition, Disk 361 
parameter block to subprogram 39 
parameter block, field in 288 
parity flag 70 
Parse Filename 183 
parsing 27 
path, network 21 
PC DOS 7 format command 7 
PC DOS 7 function dispatcher 38 
PC DOS 7 organization of book 1 
PC DOS 7 registers, see registers, PC DOS 7 
PC DOS 7 system files 11 
PC DOS 7 Version Number, Get 191 
PC DOS 7 Viewer 355 
PC DOS 7, hardware required 5 
PE flag set condition 70 
physical location of files 10 
PL flag clear condition 70 
PM event broadcast, interrupt 2FH function 
AX-530BH 120 

PM event first phase broadcast, interrupt 2FFI 
function AX-530CH 122 
PO flag clear condition 70 
pointer to next device header field 87 
pointer to strategy/interrupt routines 89 
pointers, list of 137 

POWER.EXE control. Interrupt 2FFI Function 
AH = 54H 120 
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Prefix Address, Get Program Segment 264 

prefix structure, program segment 36 

print error codes 1 1 6 

print faiiures 117 

print, resident part of 115 

Printer Output 1 47 

Printer Setup, Get 258 

Printer Setup, Set 257 

Proceed command 67 

Process (EXIT), Terminate a 233 

processor, caiiing a command 41 

Program (EXEC), Load or Execute a 230 

program (iNT 20H), terminate 107 

program code fragments 136 

program remain resident 114 

program segment 36 

program segment prefix 38 

Program Segment Prefix Address, Get 264 

program segment prefix structure 36 

Program Segment, Create New 178 

Program Terminate 142 

Q 

Ouit command 68 

R 

Random Biock Read 179 

Random Biock Write 181 

Random Read 172 

Random Write 173 

re-dispiaying Load command 62 

Read from a Fiie or Device 215 

read track on a iogicai device 292 

Read Write Pointer (LSEEK), Move 219 

Read, Random 172 

Read, Random Biock 179 

Read, Sequentiai 163 

read/write (iNT 25H/26H), absoiute disk 112 

Record Fieid, Set Reiative 176 

record number 25 

Redirect Device 261 

Redirection List Entry, Get 259 

Redirection, Cancei 263 

redirection, network 260 


reduce aiiocated memory 33 
Register command 68 
changing a fiag 70 
iist of fiag settings 70 
Register Structure, Caiiup/Down 323 
registers, dispiay 69 
remain resident, program 114 
remote device, handie is 281 
remote or iocai device 280 
removabie media determination 279 
removabie media warning 114 
Remove Subdirectory (RMDiR) 205 
Rename a Fiie 241 
Rename Fiie 166 
reopen a fiie (matrix) 213 
request header 90 
busy bit 91 

command code fieid 91 
done bit 91 

error codes, status word 91 
status fieid 91 
unit code fieid 91 

reserved fieids in fiie controi biock 23 
Reset, Disk 155 

resident (INT 27FI), terminate but stay 114 
resident part of print 115 
responding to errors 138 
response, ignore 1 1 0 
responses, invaiid 111 

Return Code of a Subprocess (WAiT), Get 234 
Return Codes, APM Error 129 
Return Codes, DPMS Error 323 
return from interrupt (IRET) 43 
return-from-interrupt instruction (iRET) 108 
ROM BIOS routine 145 
ROM communication area 34 
root directory 1 1 

routines, pointer to strategy/interrupt 89 

s 

S format option 1 1 
save area, parameter 38 
save mode of device driver 90 
Search command 71 
Search for First Entry 159 
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Search for Next Entry 161 
search in disk directory 26 
sector sequence on formatted disk 7 
sector size 7 

Segment Prefix Address, Get Program 264 

segment prefix, program 38 

segment register 137 

Segment, Create New Program 178 

Seiect Disk 156 

separators, fiiename 183 

Sequentiai Read 163 

Sequentiai Write 164 

Services Check, DOS Protected Mode 119 

Set Aiiocation Strategy 245 

set condition of fiag 70 

Set Date 186 

set device information 274 

set device parameters 288 

set device power state (1.1) 125 

Set Disk Transfer Address 168 

Set Extended Error 255 

Set Handie Count 269 

set iogicai device function caii 105 

set iogicai drive 297 

Set Printer Setup 257 

Set PSP Address 238 

Set Reiative Record Fieid 176 

Set Time 188 

Set Upper-Memory Link 247 
Set/Reset Verify Switch 189 
Setting, Get Verify 240 
SFT 364 

sharing and iock confiicts 281 
sharing mode 209 
Si register 137 
sign fiag 70 

singie biock device driver 85 
singie quotation (') 55 

Size, Fiie 175 
size, iogicai record 25 
source index 137 
SP (stack pointer) 137 
SP register 38 
SpeciaiFunctions fieid 288 
SS register 137 
stack, internai 137 


stack, user 109 
standard device fiie handie 16 
standard input bit 89 
standard output bit 89 
starting a device driver 86 
starting DEBUG 45 
static environment 38 
status 117 

status command, EMS 81 
status fieid 91 

status function caii parameter 101 
status word error codes 91 
status, end of 117 
Status, Get Current Dock 118 
STDAUX 16 
STDERR 16 
STDIN 16 
STDOUT 16 
STDPRN 16 
Storage Header 369 
String, Dispiay 151 
string, NewName 241 
string, subprogram environment 39 
Structure, Current Directory 363 
structure, Memory arena 369 
structure, program segment prefix 36 
subdirectories, iocation of 12 
Subdirectory (MKDIR), Create 204 
Subdirectory (RMDiR), Remove 205 
subdirectory entries 17 

subfunction caiis for code page switching 282 
submit fiie 1 16 

Subprocess (WAiT), Get a Return Code of 
a 234 

support of expanded memory 301 
swapping, appiication 325 
swapping, task 325 
Switch, Set/Reset Verify 189 
system date and time 44 
System Fiie Tabie 364 
System Vaiue, Get or Set 195 

T 

Tabie, System Fiie 364 
task-swapping 325 
activate session 350 
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task-swapping (continued) 

API info struc data structure 331 

build call-out chain 336 

client initialization 327 

client int 2FH handler 327 

client int 2FH handler functions 335 

client termination 330 

client, the term 326 

create session 352 

destroy session 353 

detect swapper (function 4B02FI) 335 

Function Descriptions 334 

get version 340 

hook call-out 342 

identify instance data 338 

init swapper 346 

instance item struc data structure 333 

mainframe communications software 325 

pending creation of a new session 329 

pending session switch 328 

protocol 326 

query API support 344 

query suspend 347 

session active 351 

suspend session 349 

swapper exit 354 

swapper ver structure 333 

switch call back info data structure 330 

task-swapper call-in functions 339, 345 

task-swapper Int 2FFI handler functions 335 

test memory region 341 

TSR programs 325 

unhook call-out 343 

Win386 startup info struc data structure 332 
with Windows 326 
terminate (INT 20FI), program 107 
Terminate a Process (EXIT) 233 
terminate address (INT 22FI) 107 

terminate but stay resident (INT 27FI) 114 

Terminate Process and Remain Resident 192 
Terminate, Program 142 
terminating the input queue 102 
terminators, filename 183 
time in a directory structure 19 
Time, Get 187 

Time, Get/Set File's Date and 242 


Time, Set 188 
time, system 44 
Toolkit, OS/2 356 
Trace command 72 
track, format/verify a 293 
TrackLayout field 291 
Transfer Address, Set Disk 168 
transfer area, disk 26 

u 

UMB support 94 
Unassemble command 74 
unit code field 91 
unit field 89 

unlocking media drive control strings 278 
unopened file control block 23 
UP flag clear condition 70 
user stack 109 

using PC DOS 7 function calls 135 
utility, DEBUG.COM 45 
utility, DISKCOMP 45 

V 

values in a command code 91 
vector (INT 24FI), critical error handler 108 
vector table 34 
Vector, Get Interrupt 198 
Vector, Set Interrupt 177 
vectors, requesting and specifying the 
interrupt 44 
verify a track 293 
Verify Setting, Get 240 
Verify Switch, Set/Reset 189 

w 

word fields in device header 87 
wraparound 100 
Write command 76 
Write to a File or Device 216 
write track on a logical device 292 
Write, Random 173 
Write, Random Block 181 
Write, Sequential 164 


Index 381 
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zero flag 70 
ZR flag set condition 
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